Call another mod
A mod offers methods to other mods by returning them from setup, as a VS Code extension returns its API from activate. Another mod lists it as a dependency and calls those methods through mod.dependencies, typed from the provider's own types file.
Offer methods: return them from setup
What setup returns is the mod's API: an object whose every value is a method. Each method gets the caller's input and returns its result or a promise of it. It reaches the provider's mod and state through setup's scope. Inputs and results cross from one plugin to another, so keep them plain JSON data. A setup that returns anything else stops the mod with <mod>: setup returns its API, an object of methods other mods call, or nothing. A one-line setup returns what its call returns, so setup: () => sessions.current.onPrompt(…) offers that Subscription's remove to other mods. Give such a setup braces.
import { defineMod, fs } from '../node_modules/@cmodjs/core/mod.js'
export const provider = defineMod({
name: 'provider',
setup() {
return {
lines: async ({ path }: { path: string }) => (await fs.read(path)).split('\n').length,
}
},
})A call that reaches the mod while it is still starting waits for setup to return.
Type the methods: CmodDependencies
The provider types the methods its setup returns in types/index.d.ts, and its .claude-plugin/plugin.json names that file as "types": "./types/index.d.ts". The file adds the mod to CmodDependencies, which the Claude Mod Manager (cmod) plugin declares on the claude-code module:
export type Provider = {
lines(input: { path: string }): Promise<number>
}
declare module 'claude-code' {
interface CmodDependencies {
provider: Provider
}
}- Each method takes one input and returns a promise.
- Once the name is in
CmodDependencies,tscchecks what the provider's ownsetupreturns against it, so a method that returns another shape failscmod check. - A types file augments only
'claude-code'. Claude Code refuses a types file that augments any other module.
Call the methods: mod.dependencies
A mod that calls the provider lists it in its own .claude-plugin/plugin.json, and Claude Code installs it with the mod:
"dependencies": [{ "name": "cmod", "version": ">=8.0.0" }, "provider"]Write the dependency bare, by its name alone. Claude Code looks for a bare dependency only in the mod's own marketplace, so cmod publish lists the provider there, from the release branch of the GitHub repository that the "repository" of the provider's plugin.json names. Install or link the provider before you publish, or cmod publish stops and says to. A dependency that names its "marketplace" loads for the people who install your mod, but not from the marketplace cmod link writes for your checkout.
A provider that changes or removes a method breaks every mod that calls it, and with automatic updates the provider can update first. Name the versions you tested with a range, and Claude Code turns your mod off with a clear error instead of letting its calls fail one by one:
"dependencies": [{ "name": "cmod", "version": ">=8.0.0" }, { "name": "provider", "version": "^1.0" }]Claude Code checks the range against the provider's version when it loads your mod. Every mod's marketplace lists cmod and each provider from its git repository, so Claude Code also installs it at the highest <name>--v<version> tag inside the range, which cmod publish pushes for every release (Claude Code's plugin dependencies).
cmod is a provider too, with one difference: every newer cmod runs every mod built on an older @cmodjs/core. So a mod names only the oldest cmod it runs on, which the @cmodjs/core it bundles names as oldestCmodVersion in its records.js, as >=8.0.0. When the mod needs a newer cmod, such as one whose cmod plugin carries out a call the mod makes, write that minimum as >= its version, as >=8.1.0. cmod check writes the newer of the two whenever the mod's @cmodjs/core changes, and cmod publish refuses a release whose range is not >= a version at or above oldestCmodVersion. A caret range such as ^8.0.0 stops Claude Code from updating cmod past 8.x for every mod on the computer, so leave it to cmod check.
Each mod's marketplace lists its own copy of cmod and of each provider, and Claude Code loads only one copy of each. When a mod needs a newer cmod than a copy Claude Code installed, the cmod plugin updates every copy of cmod, and when two copies of any plugin differ, it updates every copy of that plugin. Then each session offers Reload, so a mod never waits for the person to update its providers, only to press Reload.
Claude Code then lays the provider's types file beside the mod's own types, so the call is typed:
import { defineMod, sessions } from '../node_modules/@cmodjs/core/mod.js'
export const myMod = defineMod({
name: 'my-mod',
setup(mod) {
sessions.current.onToolResult(async ({ files }) => {
for (const path of files.changed) mod.log(`${path}: ${await mod.dependencies.provider.lines({ path })} lines`)
})
},
})Call a mod only when it runs: mods.isLoaded
A mod that works without another mod, and only uses it when the person has it, does not list it, because Claude Code installs every listed dependency for everyone who installs your mod. Ask whether it runs first, then call it through mod.dependencies as usual:
if (await mods.isLoaded('provider')) await mod.dependencies.provider.lines({ path })isLoaded(name: string): Promise<boolean>isLoadedanswers true when the mod runs in this Claude Code process, as one Claude Code loaded or one run from its checkout with--plugin-dir. A mod the person installed but turned off answers false.- Claude Code lays a provider's types file beside your mod's only for a listed dependency, so type the methods you call in your own
types/index.d.ts, with the shape the provider's types file exports, such asinterface CmodDependencies { provider: Provider }. - A mod that calls
mods.isLoadedruns on cmod 5.4.0 or later, which thecmodrangecmod checkwrites says.
Interfaces: several mods answer one name
A provider is a mod, or a mod's program, that implements a feature an interface defines. It follows VS Code's providers: an extension registers a HoverProvider with registerHoverProvider, and VS Code asks every registered HoverProvider for its hover. A caller asks providers(name) for every provider that runs and calls each one, where a dependency is one mod your mod calls by name. So a terminal app, a remote device, or a Markdown styler can each come from any mod.
An interface is named <mod>/<Name>, after the mod that defines it, such as demo/Platform, and cmod defines six:
cmod/Sessionslists, searches, and reads sessions, acts on them, and tells aChangefor each session that starts or stops running, is visited or deleted, or changes its tasks, goal, or status, as one VS CodeFileSystemProviderreads, writes, and reports changes for its scheme.cmod serveprovides it for this computer, thecmod serveof each device acmod/Devicesprovider names provides it for that device, and a mod whose program serves another device's sessions provides it for that device (session.md).cmod/Devicessays where thecmod serveof each of your other devices listens, or carries its messages, socmod servereaches the providers there (cmod/Devices).cmod/UIlists, draws, and presses each session's widgets, views, and pages, and tells aChangewhen a mod adds or removes one and aRedrawwhen one may draw new data, so an app such as the browser app draws every mod's UI. Each session's cmod plugin answers it for its own session, andcmod servesends each call to the plugin that holds the session the call names (ui.md).cmod/Terminalreads a session's screen, types keys into it, and shows it in a pane.cmod serveprovides it, first in the list, for each session that runs in a terminal of herdr-core, the terminals the Herdr app shows, and answers not held for any other, so a mod whose program hosts other terminals provides it for those. Its provider tellsShown { session, place }after eachshowandPressed { session }after eachpress, so a program that keeps track of which sessions are in use hears an agent's use of one.cmod/Providerstells aChange { interface, device }each time a provider of an interface starts or stops: a program on this computer or on a devicecmod servereaches, or a mod's session code in your own session, and once for each interface you listen for when a device is reached or lost, as VS Code'sextensions.onDidChangefires when the set of extensions changes.cmod serveof this computer provides it, so a caller that waits for a provider listens and callsproviders(name)again on eachChange:tsconst [watch] = await providers('cmod/Providers') watch?.onChange({ interface: 'demo/Platform' }, async () => platforms.set(await providers('demo/Platform')))cmod/Styledraws Markdown in a mod's own style. Every mod with a Markdown style provides it, with noprovidecall (ui.md).
@cmodjs/core types cmod's own interfaces, so they type-check in every mod. The mod that defines any other interface types it in its types file, on CmodInterfaces, with its methods and the events it tells:
declare module 'claude-code' {
interface CmodInterfaces {
'demo/Platform': {
methods: { machines(region: string): string[] }
events: { MachineChange: { readonly name: string } }
}
}
}A mod provides an interface with provide, imported from mod.js beside providers, as VS Code's registerXProvider is a function of its namespace. provide returns a Provided: its remove() stops providing, its tell tells one of the interface's events to every onE listener on this provider, as a VS Code provider fires its own onDidChange event, and its ask asks every beforeE listener before the provider acts, as VS Code's onWillSaveTextDocument waits for its listeners.
provide<Name extends InterfaceName>(name: Name, methods: InterfaceMethods<Name>): Provided<Name>
type Provided<Name> = Subscription & {
tell<Event>(event: Event, payload: EventsOf<Name>[Event]): void
ask<Event>(event: Event, payload: EventsOf<Name>[Event]): Promise<unknown[]>
}ask asks the listeners one at a time and resolves with each answer in the order it asked, leaving out a listener that answered nothing. It stops at the first answer that holds refuse, so no listener after it is asked. Each listener runs within its own timeoutMs, 10 seconds when it gives none, and a listener that throws, passes its timeoutMs, or cannot be reached counts as its onFailure says: 'pass', the default, leaves its answer out, and 'refuse' answers { refuse: '<its error>' }. A provider reads the answers as its interface defines them:
const rules = provide('demo/Rules', {})
const answers = (await rules.ask('Check', { tool: 'Bash' })) as { readonly refuse?: string; readonly rules?: Record<string, 'off' | 'warn'> }[]Another mod in the session answers with a beforeE listener on that provider:
const [rules] = await providers('demo/Rules')
rules?.beforeCheck((check) => (check.tool === 'Bash' ? { rules: { 'no-rm': 'off' } } : undefined), { timeoutMs: 2000 })From session code, provide answers the methods while the mod runs in that session, and only callers in that session reach it and hear what it tells, as a VS Code window's provider serves only that window. The cmod plugin carries each tell and ask to the session's listeners, as cmod serve carries a program's, so a tell inside a method that answers a call, or an ask inside the mod's own beforeToolCall listener, still reaches the caller:
const platform = provide('demo/Platform', { machines: async (region) => listMachines(region) })
platform.tell('MachineChange', { name: 'eu-1' })From a program that a program job with singleInstance or isService runs (jobs.md), provide answers the methods and tells the events for the whole computer, through the program's connection to cmod serve, which connect() opens:
import { provide } from '@cmodjs/core/mod.js'
import { connect } from '@cmodjs/core/rpc.js'
await connect()
const platform = provide('demo/Platform', { machines: async (region) => listMachines(region) })
platform.tell('MachineChange', { name: 'eu-1' })connect: a program's connection to cmod serve
connect, imported from rpc.js, opens the program's one connection to this computer's cmod serve, the hub that holds every program's providers and carries each call to the provider it names, as VS Code's window holds every extension's providers:
connect(): Promise<Connection>
type Connection = {
call(name: string, method: string, params: readonly unknown[]): Promise<unknown>
listen(name: string, event: string, listener: (payload: unknown, signal: AbortSignal) => unknown): Subscription
tell(name: string, event: string, payload: unknown): void
ask(name: string, event: string, payload: unknown): Promise<unknown[]>
close(): Promise<void>
}- It names the mod by
CMOD_MODand the program byCMOD_PROGRAM, whichcmod programsets for each program it starts, and rejects withconnect() names its mod by CMOD_MOD, which cmod program sets for every program it starts, and CMOD_MOD is not set.outside one. - It resolves once
cmod serveanswers onserve.sockin the cmod store, and connects again, and provides again, whenevercmod servestarts again. - After it, the program imports
provideandprovidersfrommod.js. Every other import throws<mod>'s program imports only provide and providers from @cmodjs/core/mod.js, because <import> belongs to a Claude Code session. tellis whatProvided'stellruns: it tells everyonElistener on this program's provider ofname.askis whatProvided'saskruns: it asks everybeforeElistener on this program's provider ofname, in a session or a program, on this computer or a devicecmod servereaches.callandlistenreach an interface without picking a provider:cmod serveanswerscmod/Sessionsandcmod/UIitself, sends any other interface to its one provider, on this computer or a device it reaches, and refuses when no program or several provide it.providerspicks one.callrejects with<interface>.<method> passed its 30 s deadlinewhen the provider has not answered after 30 seconds, such as a provider on a device that went to sleep mid-call. It then sends$/cancelRequest, so the provider's handler sees its signal abort.closeends the connection, andcmod servedrops the program's providers with it.- A program that only provides prints no address, so its job's
ready()rejects once it runs. Its mod waits with the job'sprovider(name)instead, which resolves with that program's provider ofnameonce the program provides it (jobs.md).
A cmod/Sessions provider answers every method its type in the cmod plugin's types file names. Each method on one session takes the session's id first. For a session the provider does not hold, the method throws NotHeld, imported from rpc.js, so cmod asks the next provider, as a VS Code FileSystemProvider throws FileSystemError.FileNotFound. Its message is This provider holds no session <id>., which the caller reads when no provider holds the session. Any other error ends the call with its message, and cmod asks no further provider:
import { provide } from '@cmodjs/core/mod.js'
import { connect, NotHeld } from '@cmodjs/core/rpc.js'
await connect()
provide('cmod/Sessions', {
read: async (session, part, options) => {
const device = await deviceOf(session)
if (device === undefined) throw new NotHeld(session)
return device.read(session, part, options)
},
...
})startTask takes the whole task, device included: a provider that serves the device the task names starts the session there and answers its task, and any other throws NotHeld. The provider tells a Change with part: 'running' when one of its sessions stops running, which closes the task of the session that started it.
A caller asks providers, imported from mod.js, for the providers that run now, and calls each one's methods, typed from the interface:
providers<Name extends InterfaceName>(name: Name): Promise<InterfaceProvider<Name>[]>for (const platform of await providers('demo/Platform')) {
mod.log(`${platform.mod}: ${(await platform.machines('eu')).join(', ')}`)
platform.onMachineChange((machine) => mod.log(`${machine.name} changed`))
}- Each provider names its
mod, itsprogramwhen a program provides it, and itsdevice, the{ id, name }of the computer it runs on, in the shapedevice.read()answers (mod.md). The list holds every mod that provides the interface in this session, every program that provides it on this computer, whichcmod serveholds, and every program that provides it on a devicecmod servereaches (cmod/Devices), in no set order. - Each method returns a promise of what the provider's method returns, and rejects with the provider's error. A method the provider lacks rejects with
This program answers no <interface>.<method>., or<mod> provides no <interface>.<method>.from session code. A method that has not answered after 30 seconds rejects with<interface>.<method> passed its 30 s deadline, as amod.dependenciescall does (When a call fails). - Each event
Ehas anonEand abeforeEmethod, as the session's listeners do (session.md): anonElistener hears what the provider tells withProvided'stell, and abeforeElistener's answer reaches the provider that asks it withProvided'sask, or a program that asks it with$/before, which reads it as it defines. Both take a matcher,timeoutMs, andonFailure. - A provider that stops running leaves the list at the next call of
providers. A program's providers leave when its connection closes, and a program that dies closes it at once, becausecmod servecloses a connection whose poll the program left. A call to a provider that left fails with<mod>'s <program> program does not run, so it answers no <interface>.
A program in a language with no connect() speaks the wire connect() speaks, JSON-RPC 2.0 over HTTP on serve.sock in the cmod store:
POST /rpc/connectopens a connection and answers{ "connection": <id> }.POST /rpc/<id>takes a JSON-RPC message or batch from the program and answers 204.GET /rpc/<id>answers the messagescmod servehas for the program, as a list, within 8 seconds, empty when it has none: the answers to its requests, and the requests and notifications of its callers.DELETE /rpc/<id>closes the connection, and so does aGETthe program leaves before its answer, or no poll for 30 seconds. A call on a closed connection answers 410, and the program connects again.$/providewith{ interface, mod, program }makes the connection that program's provider of the interface, and$/unprovidewith{ interface }stops it.cmod servesends the program each call as a request that names<interface>.<method>, such asdemo/Platform.machines, with the method's arguments as itsparamsarray.- A
cmod/Sessionsprovider answers a call on a session it does not hold with the JSON-RPC error code-32098, the answerNotHeldsends, and cmod asks the next provider. Any other error code ends the call with the error's message. cmod servesends each listener as$/listenwith{ id, interface, kind, event, args?, matcher?, after? }, and$/unlistenwith{ id }removes it. The program tells anonlistener with the notification$/on{ id, payload, cursor }, and asks abeforelistener with the request$/before{ id, payload }, whose result is its answer. A listener that namesafter, a cursor it last heard, hears the events since.$/cancelRequestwith{ id }cancels a request.$/providerswith{ interface }answers each program that provides it as{ mod, program, device }, and$/callwith{ interface, method, args, mod, program, device }calls that program's method.$/providerswith{ interface, device }answers only the providers of this computer, and only whendeviceis its id, which is how onecmod serveasks another.$/providerwith{ interface, mod, program }answers{ mod, program, device }once that program on this computer provides the interface, at once when it already does.$/cancelRequeststops the wait.
cmod/Devices: providers on your other devices
A mod that links your devices, such as one that reaches them over ssh, a tailnet, or a relay, provides cmod/Devices from its program. For each other device it gives where that device's cmod serve listens, or carries that cmod serve's messages itself, as a VS Code RemoteAuthorityResolver answers an address or a ManagedMessagePassing:
'cmod/Devices': {
methods: {
devices(): { id: string; name: string; address?: string }[]
send(device: string, message: unknown): void
}
events: { Change: { readonly device: string }; Message: { readonly device: string; readonly message: unknown } }
}idis the device's cmod device id, whichcmod device --jsonprints on that device, andnameits name.cmod serveasks everycmod/Devicesprovider on this computer for its devices when it provides the interface, reaches thecmod serveof each device, and lists that device's providers beside this computer's, each with itsdevice.- The provider tells
Change, with the id of the device that changed, whenever its list changes.cmod servethen reads every list again: it reaches a new device, reaches again a device whose address or provider changed, and drops a device no list holds.
A device with an address is reached there. The address is where that device's cmod serve answers the wire above: a unix socket path, such as the end of an ssh tunnel, or an http:// URL. The mod opens the link its own way, and cmod reaches the address with its own JSON-RPC over HTTP, which polls every 8 seconds.
A device with no address is reached through its provider, over one message channel. cmod serve sends each JSON-RPC message for that device's cmod serve with send, and the provider tells each message from that device as Message, in the order they came, and never reads one. A provider that links devices through a relay carries them both ways:
await connect()
const devices = provide('cmod/Devices', {
devices: () => relay.peers().map(({ id, name }) => ({ id, name })),
send: (device, message) => relay.send(device, message),
})
relay.onMessage((device, message) => devices.tell('Message', { device, message }))
relay.onPeersChange((device) => devices.tell('Change', { device }))- The channel is a peer link: the same
cmod serveboth asks and answers over it, so each device's provider lists the other. - Nothing polls across it. It carries a message only when a call, a listener, or an event needs one.
- Each
cmod serveopens its end with the notification$/link{ link }, and answers the other end's with$/link{ link, answers }. It lists that device's providers once the two ends linked, so a device whosecmod servenever answers stays out ofproviders. - A
$/linkfrom a device it already linked with means that device'scmod servestarted again.cmod servefails each call still waiting on the old link withThe connection closed: the cmod serve of <device> linked again, and listens there again. - A call whose message
sendfails rejects with<mod>'s <program> program carried no message to <device>: <its error>. cmod servecarries each call and listener on another device's provider to that device'scmod serve. Eachcmod serveoffers another device only its own computer's providers, never ones it carries, so a call takes one hop even when two devices list each other.- A session's own providers stay in that session, as a VS Code window's do.
When a call fails
A call that cannot answer rejects with one of these reasons:
<provider> is not installed. Install it in Plugins.
<provider> is not set up: <why its setup failed>
<provider> is installing. Try again when it's ready.
<provider> has no method <method>.
<provider>: <the message of the error the method threw><provider> is not installedcovers a provider whose code did not load. The caller's error toast shows aPluginsbutton, which opens Claude Code's/plugin.<provider> is not set upcovers a provider the person declined to install and one whose install failed, and names why. The provider's own toast shows the same reason, withRetryorInstall.<provider> is installingcovers a provider whose install step still runs 5 seconds after the call. A provider that is installing or only starting makes the call wait for it, up to 5 seconds.- When the provider is disabled, Claude Code unloads the mod that lists it, with its own error, which starts
Dependency "<provider>" is disabled. - A call fails with
mod.dependencies.<provider>.<method> passed its 30 s deadlinewhen the other mod takes longer than 30 seconds. A call to a provider's method keeps the same 30 s deadline, from session code and from a program, and fails with<interface>.<method> passed its 30 s deadline, such asdemo/Platform.machines passed its 30 s deadline, and cancels the request it left with the provider. A listener is no call, so it keeps no deadline, andProvided'saskbounds each listener by its owntimeoutMs. A job bounds the whole function that makes the call by its own deadline (jobs.md), so a slow call insideslashCommandcan fail the command first, with/<command> passed the 30 s deadline of slashCommand.
notInstalled(name: string): stringnotInstalled, exported from mod.js, returns the first reason for a mod name: <name> is not installed. Install it in Plugins. A test uses it to expect that message.
Test the calls
testMod(myMod, { dependencies: { provider: { lines: async () => 3 } } }) answers the provider's methods with the functions given. A call to a mod the test does not fake fails with <provider> is not installed. Install it in Plugins., as in Claude Code. testing.md covers it.
testMod(myMod, { providers: [{ name: 'demo/Platform', mod: 'demo', program: 'platform', methods: { machines: () => ['eu-1'] } }] }) fakes a provider of an interface, on this computer or on a device it names, and tested.providers tells its events and asks its beforeE listeners (testing.md).
A test of the provider's own methods fires cmod.call, as a caller's mod.dependencies does. The answer is { value } with what the method returned, or { deny } with the reason it failed:
const tested = testMod(provider, { files: { '/work/a.ts': 'a\nb\nc' } })
expect(await tested.fire('cmod.call', { to: 'provider', method: 'lines', input: { path: '/work/a.ts' } })).toEqual({ value: 3 })