cmod commands
The cmod command of Claude Mod Manager (cmod) builds, checks, and publishes mods, and installs them. npm i -g @cmodjs/cli puts it on PATH. cmod <command> --help prints a command's arguments, and cmod --version prints the version.
Each command below restates what cmod <command> --help prints, for a mod author. The help text is the full word.
Build a mod
cmod new
cmod new <name> [--project]Creates a mod in ./<name>: a defineMod with one listener, a view, a widget, and a hotkey that shows the view, a Skill, a test, and a CHANGELOG.md (mod.md). Then installs its packages.
<name>is lowercase letters, digits, and-, starting with a letter.--projectcreates a project-scope plugin in./.claude/skills/<name>/of the repository in the current folder, which loads for everyone who trusts the repository. Run it in the repository's root.CMOD_COREsets the@cmodjs/coredependency it writes. By default it writes^<the version of this cmod>. To build against an unreleased@cmodjs/core, point it at a packed tarball, such asfile:/path/to/cmodjs-core-<version>.tgz. Only a.tgzworks: a folder installs as links into that folder, andclaude plugin validate --strictrefuses the mod.- When the packages fail to install, it deletes the new folder.
cmod link
cmod link [path] [--option key=value]...Loads the checkout at path (default: the current folder) in every Claude Code session, the running ones too, in place of the installed mod. Installs the cmod plugin when Claude Code lacks it, unless the checkout is cmod itself. Then installs the checkout's packages, builds the program cli/ declares and links it into cmod's programs folder and ~/.local/bin, and runs the checkout's install step. The build is bin/<program>/<version>/<program>.linked in the cmod store, beside the released program of the installed copy, which it never replaces.
It loads the checkout through a marketplace cmod keeps in the checkout's parent folder:
- It lists the checkout in
<parent>/.claude-plugin/marketplace.json, named<parent folder>-linked, beside the cmod plugin from thereleasebranch ofheyJordanParker/cmod, so the mod'scmoddependency resolves in that marketplace. Every checkout linked from one folder shares its marketplace. The checkout's own.claude-plugin/marketplace.json, the onecmod publishwrites, stays as it was. - It adds that file, and
<parent>/.claude/settings.local.jsonbeside it, to the parent's.git/info/excludewhen the parent is inside a git repository. - It adds the marketplace to Claude Code with
claude plugin marketplace add <parent> --scope local, which declares it in<parent>/.claude/settings.local.json, so thesettings.jsonyou share between computers holds no path of this one, the waynpm linkkeeps a link out of the sharedpackage.json. Then it installs<mod>@<parent folder>-linkedfrom it, which loads the checkout's own files in every session, in any project, at the next reload. - It turns off the installed copy of the mod from any other marketplace, and records it in
links.jsonin the cmod store, socmod unlinkturns that copy back on.
It refuses a parent folder whose .claude-plugin/marketplace.json cmod did not write. Once a change builds, cmod watch tells every session, and each one still running the old build offers Reload, 35 seconds after the last change and between turns. To test your edits without pressing Reload, start the session with claude --plugin-dir <checkout>: Claude Code then reloads the checkout by itself between turns, in that session only, and that session offers nothing for it.
--option key=valuesets one of the mod's options throughclaude plugin configure, once per option, under the linked id,<mod>@<parent folder>-linked. It refuses a key the mod does not declare, and names the keys it does (options.md).
cmod unlink
cmod unlink [path]Stops loading the checkout at path (default: the current folder) in every Claude Code session. Uninstalls it through Claude Code and takes it out of the marketplace in its parent folder. Once that marketplace lists no checkout, it uninstalls the cmod plugin the marketplace installed, removes the marketplace and its declaration in <parent>/.claude/settings.local.json from Claude Code, and deletes its file and its line in .git/info/exclude. The line for settings.local.json stays while that file does, because Claude Code leaves it behind, empty. Then it turns back on the copy of the mod cmod link turned off and sets up the copy of the mod Claude Code still has, which keeps the mod's data and secrets and links the released program that copy already has, with no download, then deletes the program cmod link built. Only when Claude Code has no other copy does it run the checkout's uninstall step and remove what cmod set up.
cmod check
cmod check [path]Runs every check this device can run on the mod at path (default: the current folder), each failure with its fix:
- Installs its packages.
- Checks its layout.
- Checks that each step runs a script.
- Checks that
package.json"os"and"cpu"list only machines cmod runs mods on, darwin and linux on arm64 and x64, and that the install step downloads a program for each machine they list. - Checks the permission check. It adds
"approve": truetopackage.json"cmod"when the mod allows or asks on Claude Code's permission check andhooks/register.tscallsregisterPermissionCheck. It fails a mod whosesrc/hears the permission check whileregister.tsdoes not callregisterPermissionCheck, and a mod on@cmodjs/core5.0.0 or later whosepackage.json"cmod"still declares"permissions", with the fixDelete "permissions" from package.json "cmod", and write "approve": true there if the mod approves tool calls. - Reads the metadata of every file in the mod, and names each file whose metadata cmod cannot read.
- Writes the options
defineModdeclares into.claude-plugin/plugin.jsonuserConfig, and its hotkeys intopackage.json"cmod"hotkeys, keeping each file's own formatting, so Claude Code shows the options in/config(options.md). It loadshooks/register.tsto read them, without starting the mod. - Writes the
cmoddependency in.claude-plugin/plugin.jsonas>=the oldest cmod the@cmodjs/corethe mod installed runs on,oldestCmodVersionin itsrecords.js, such as>=8.0.0, so every newer cmod runs the mod. When the mod needs a newer cmod than that, such as one whose cmod plugin carries out a call the mod makes, write that minimum yourself as>=its version, such as>=8.1.0, andcmod checkkeeps it. It raises only a minimum below that oldest cmod, and writes any other range as>=that oldest cmod. A@cmodjs/corethat does not exportoldestCmodVersionruns on the cmod of its own version, so the range is>=that version, such as>=4.3.4. A mod still on@cmodjs/core3 keeps its own range (dependencies.md). Claude Code turns a mod off when its cmod is older than that dependency, socmod checkfirst compares it with every cmod plugin Claude Code installed on this device. When an installed copy is older, it updates them ascmod update cmoddoes. When one is still older, as when your@cmodjs/coreneeds a cmod newer than every published one, the check fails, keeps the old dependency, and names the@cmodjs/coreto install instead. When a cmod linked from a checkout is older, the check fails the same way and says to pull that checkout, because no update reaches it. On a device without Claude Code or without a cmod plugin, such as CI, it writes the dependency at once. - Checks the imports of every file the release ships, the files
cmod publishwould release. It fails a file that imports theclaude-codemodule, because every type a mod writes comes from@cmodjs/core(index.md). A provider's types file adds to that module withdeclare module 'claude-code', which imports nothing, so the check keeps it. A folder the release leaves out, such as a library its"files"list does not name, may import anything. - Looks for prebuilt binaries outside
cli/. - Builds the release in a temporary folder as
cmod publishbuilds it, with its"files"list and its bundled hooks module, and validates the release with Claude Code,claude plugin validate --strict. So it fails on a pathplugin.jsonnames that"files"leaves out, a"files"path that matches no file in the mod, and each reason a bundle fails, and prints every line the validator writes. Then it deletes the folder. - Compiles it against Claude Code's API with
tsc, withtsconfig.json, and then withtests/tsconfig.jsonwhen it exists.cmod newwrites both: the root config leaves Bun out ofsrc/, which runs inside Claude Code, and the tests config addsbun-types, so a test can run a real program withBun.spawnor read files withnode:fs. When.claude-plugin/types/is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in oneclaude -prun with a config folder of its own and no model to reach, so the run sends nothing. - Lints it with
oxlint. - Runs, with
bun test, every test file that does not importclaude-code/testing. Whenbunfig.tomlnames a[test]root, it runs only the test files under that folder, asbun testdoes. - Runs, with
claude plugin test, the test files that importclaude-code/testing. It skips this when none does. - Checks its name against other plugins. Only a project plugin, in
.claude/skills/<name>/of a repository, runs this check: it fails when an installed or linked plugin has the same name and hides the project plugin. Any other mod passes it at once.
The checks that read the mod's files, the metadata, imports, binaries, permission check, and test files, skip every file git ignores, such as scratch work in an ignored folder, because no release holds it.
cmod check fetches tsc 7.0.2 and oxlint 1.86.0 into the cmod store the first time. A check it cannot run, such as one that needs Claude Code on a device without it, fails with the reason, and the later checks still run. It ends with a count of passed, failed, and skipped checks, and exits 1 when one failed.
cmod try
cmod try <owner/repo | path>... [--option key=value]... [--home <folder>] [-- claude arguments]Starts one throwaway Claude Code session with mods set up, for trying a mod by hand or testing it with an agent. Installs each mod's packages, installs the cmod plugin when Claude Code lacks it, and runs each mod's install step. Then starts one Claude Code session that loads every mod with --plugin-dir.
--option key=valuesets one option of the mod. With several mods, write--option <mod>.key=value.- The session runs with a new home folder, so it sees only the mods named here and changes none of your Claude Code settings, mods, key bindings, or history. The folder is deleted when the session ends.
- The session stays logged in as you, with no login screen:
- On macOS, Claude Code reads your login from the keychain, which
cmod trylinks into the new home as~/Library/Keychains. Deleting the home removes only the link. - Elsewhere,
CLAUDE_SECURESTORAGE_CONFIG_DIRpoints Claude Code at the folder that holds your login, so it reads and refreshes that login where it is. ANTHROPIC_CONFIG_DIRpoints at your~/.config/anthropiclogin profiles, andCLAUDE_CODE_OAUTH_TOKENandANTHROPIC_API_KEYpass through.
- On macOS, Claude Code reads your login from the keychain, which
- The session keeps how Claude Code reaches the model and what it must never do, so a try is as safe as your own session. From your
settings.jsonit keepsenv(a proxy orANTHROPIC_BASE_URL), the credential helpers (apiKeyHelper,awsAuthRefresh,awsCredentialExport,gcpAuthRefresh,otelHeadersHelper,proxyAuthHelper), the login pins (forceLoginMethod,forceLoginOrgUUID,forceLoginGatewayUrl,gatewayInternalNetworks),sandbox, andpermissions.deny. From~/.claude.jsonit keeps your account and the API keys you approved. A~/in a helper still means your own home. Hooks, plugins, allow rules, the model, and every other preference stay behind. Managed settings apply as always. --home <folder>runs in that folder and keeps it, so the nextcmod try --home <folder>starts from it.--home ~runs in your own home, with your settings and mods.- A checkout's program is built from its
cli/the waycmod linkbuilds it, with your own home and environment, so the build finds your toolchains and caches. A GitHub mod's program downloads from the GitHub release of the mod's version, so it fails untilcmod publishhas released that version. - When the session ends, even when its terminal closes, it runs each mod's uninstall step and deletes its record, data folder, cache folder, approval, key bindings, and program, so the mod stays uninstalled. A checkout already set up from the same folder keeps its setup.
- A GitHub mod is cloned into a temporary folder, which is deleted too.
- A mod another folder has set up in that home is refused, so
cmod trynever replaces an installed copy. - Arguments after
--go toclaude, such as-- -p "hello". An agent tests a mod with onecmod try <path> -- -p "<prompt>"run.
cmod log
cmod log [<mod>] [--json]Prints the Log that Settings shows in cmod's entry, newest first: each failure and warning a mod or cmod met in any session on this computer, with the text Copy gives, the versions of the mod, its @cmodjs/core, cmod, and Claude Code it happened on, and how often it repeated in its session (ui.md). <mod> keeps one mod's entries, so an agent working on a mod reads what went wrong in every session without opening Settings. --json prints the entries as a list of { mod, id, level, message, details, at, firstAt, count, session, versions }.
cmod publish
cmod publish [path] [--dry-run]Releases the mod at path (default: the current folder) at the version in its plugin.json.
- Runs the checks of
cmod checkthat read what the release ships, steps 2 to 10 ofcmod check, and releases nothing when one fails, so a mod whose layout, steps, options,cmoddependency, or imports are wrong never reaches the people who install it. It runs notsc, lint, or tests:cmod checkruns those on each commit, on your computer and in CI, and the release is built from a commit they already passed, ascargo publishbuilds a crate and runs none of its tests. Wherecmod checkwrites a fix, such as the optionsdefineModdeclares intouserConfig, its hotkeys, or thecmoddependency,cmod publishfails that check instead and leaves the file as it is, with the fixRun cmod check, which writes it, commit <file>, then run the command again.So--dry-runchanges no file either. - Builds the release from the files git does not ignore, leaving out
cli/,.github/, and.claude/. A"files"list inpackage.jsonlimits the release to the paths it lists, a path in those three folders included, such ascli/bin/<launcher>, plus the folders of the install and uninstall steps,.claude-plugin/,package.json,tsconfig.json, the README, the license, andCHANGELOG.md, the waynpm publishreads it.tsconfig.jsonholds the JSX settings the bundle in step 3 needs. List every folder the hooks module imports from, such as"files": ["hooks", "src", "skills"], because the bundle in step 3 is built from the release. - Bundles the hooks module that
hooks/hooks.jsonnames, with the mod's source and packages, into one readable.jsfile, writes each control character in it as a\uescape, and pointshooks/hooks.jsonat it. Anthropic's plugin directory reads a repository without installing its packages, so it can follow a mod only when all its code is in one file. Without"approve": trueinpackage.json"cmod", the bundle leaves out the code that allows and asks on Claude Code's permission check, because Anthropic's plugin directory does not list a mod that can approve Claude's tool calls (mod.md). - Checks the release's
.claude-plugin/plugin.json, and its.claude-plugin/marketplace.jsonwhen it has one, withclaude plugin validate --strict, and stops with every line the validator writes when it fails.cmod checkbuilds and validates the release the same way, so it fails first. - Commits the release as the
releasebranch, and builds the release archive from that commit. - Builds the program
cli/declares, and writesSHA256SUMSfor every file of the release. - Writes
.claude-plugin/marketplace.json, listing the archive, the cmod plugin, and each other modplugin.jsondepends on. The cmod entry points at thereleasebranch ofheyJordanParker/cmod, so the mod's"cmod"dependency resolves in this marketplace and follows each cmod release with no new publish of the mod. Each other dependency's entry points at thereleasebranch of the GitHub repository of the marketplace Claude Code added on your computer that lists it (dependencies.md). - Commits that file, tags
v<version>, tags the release commit<name>--v<version>, which Claude Code installs a version range from when a marketplace lists the mod from its git repository, pushes both tags and thereleasebranch, creates the GitHub release with every file, then pushes the branch that holdsmarketplace.json. So Claude Code never updates anyone to a release whose files are not up yet. Its notes are the version's section of the committedCHANGELOG.md, above GitHub's compare link (mod.md).--dry-runprints them. - Prints the link to paste as the Repository when you submit the mod at claude.ai/directory/manage, such as
https://github.com/owner/my-mod/tree/release. The portal reads the branch from the link, so the directory followsrelease.
The release keeps package.json, so Claude Code still installs the mod's packages for its install and uninstall steps. It keeps bun.lock too, unless a "files" list leaves it out. main keeps the source only.
It needs, and refuses to start without:
- the mod's folder as the root of a git repository with at least one commit, because the release is committed as the
releasebranch - a
## [<version>]section with notes in the committedCHANGELOG.md node_modulesin the mod's folder, frombun install, when the hooks module imports a package- each mod
plugin.jsondepends on, other than cmod, listed in a GitHub marketplace Claude Code added on your computer, so install it from its marketplace first - a
registerdeclared as a function in the hooks module, ascmod newwrites it, because the validator refuses a bundledregisterthat is not one - the
claudecommand, which validates the release - an
originremote on GitHub - a
package.jsonwith no dependency on afile:orlink:path, which no user has - a
"files"list, whenpackage.jsonhas one, whose every path matches a file in the mod - a
"program"in thecmodkey ofpackage.jsonthat names the programcli/declares, whencli/declares one - a
cmoddependency in.claude-plugin/plugin.jsonof>=the oldest cmod the@cmodjs/corethe mod bundles runs on, whichcmod checkwrites - for a real publish, a working tree with no uncommitted changes, no
v<version>or<name>--v<version>tag yet, agit pushtooriginthat succeeds, and theghcommand, which creates the GitHub release
--dry-run builds everything into a temporary folder, and pushes nothing. It writes marketplace.json there too, so the working tree stays as it was. It allows uncommitted changes and an existing tag, and builds from the working tree, uncommitted changes included. It prints the folder that holds the release, so you can read what the directory will read. A real publish deletes that folder once the release is out.
Install mods
cmod install, cmod update, cmod remove, cmod enable, cmod disable, cmod link, cmod unlink, and cmod try write the time to plugins-changed in the cmod store, then write store-changed beside it, when they finish, also when they fail partway, such as an update that updated some mods. The cmod plugin of every running session watches store-changed and Claude Code's installed_plugins.json, and reads the enabledPlugins of the user's settings.json each time Claude Code reports that file changed and at each prompt, whether a cmod command, /plugin, claude plugin, or Claude Code's automatic update changed them. While plugins-changed, installed_plugins.json, or enabledPlugins differs from what the session loaded, the session keeps running the plugins it loaded and shows one Plugins changed toast with a Reload button. It names each change, such as my-mod updated to 1.3.0 or my-mod turned on, or counts them past 3, and each further change updates the same toast. The person presses Reload, which runs /reload-plugins, or when the turn ends if Claude is working, and the prompt the person is typing stays. A change back to what the session loaded, or the person's own /reload-plugins, takes the toast away. A session no app shows, such as claude -p, shows nothing. A reload keeps the prompt cache: the next request reads the whole conversation from the cache and pays only for the plugins' new content. A reload clears each mod's memory state. A device where cmod set up no mod has no store, and these commands write nothing there.
cmod install
cmod install <owner/repo | path> [name] [--option key=value]...
cmod install <name | name@marketplace> [--option key=value]...Adds the plugin's marketplace to Claude Code and installs the plugin through Claude Code. A mod also gets the cmod plugin when Claude Code lacks it, and its install step runs. Any other plugin installs through Claude Code alone, and cmod keeps no record of it.
- When the marketplace lists several plugins, name the one to install after it.
- Given
name@marketplaceof a marketplace Claude Code has added, it installs that plugin. - Given the name of a plugin Claude Code already holds, it runs a mod's install step again.
- A path holds a
/, such as./my-mod. A folder's marketplace is declared in that folder's.claude/settings.local.json, so thesettings.jsonyou share between computers holds no path of this one, and anowner/repomarketplace is declared insettings.json. In a git checkout, that file goes into.git/info/exclude, sogit statusstays clean.cmod removekeeps the line, because the marketplace and its file stay after the plugin is gone. --option key=valuesets one of the mod's options throughclaude plugin configure, once per option, so a scripted install needs no visit to/config. It refuses a key the mod does not declare, and names the keys it does (options.md).
cmod update
cmod update [name]Updates the named plugin, or every plugin Claude Code has installed, through Claude Code, then runs the install step of each mod whose version or scripts changed. A linked plugin is skipped, because saving its files updates it. When Claude Code fails to update a plugin, cmod update names it, updates the rest, and exits 1. Every running session then loads the new version.
cmod remove
cmod remove <name>Uninstalls the plugin through Claude Code. When cmod set the plugin up as a mod and Claude Code still has another copy of it, such as one from another marketplace or a linked checkout, it sets that copy up, which keeps the mod's data and secrets. When no copy is left, it runs the uninstall step cmod saved and removes what cmod set up.
cmod enable and cmod disable
cmod enable <name>
cmod disable <name>Turns the plugin on or off through Claude Code, as /plugin does, and every running session follows. A mod keeps its setup, its data, and its program while it is off, and runs no install or uninstall step either way. They refuse a plugin linked with cmod link, which cmod unlink stops loading. The Turn off and Turn on buttons in Settings run them.
cmod list
cmod list [--json]Lists every plugin Claude Code has installed or linked, with its version. A mod shows whether cmod set it up, and any other plugin shows whether Claude Code enabled it. A plugin Claude Code turned off shows Claude Code's reason, such as Requires "cmod@market" >=4.2.0, installed 4.0.0. It also lists every mod Claude Code removed whose uninstall step has not run yet. A mod that runs a program as a service of this computer, for a program job with isService (jobs.md), names it, as in ready, runs <program> as a service of this computer.
--jsonprints the list as JSON: one object per row with itsname,version,state, andunsatisfied, the dependencies Claude Code turned the plugin off for because they are older than the plugin needs. A plugin whose folder exists also hasfolder, the folder it runs from: the checkout for a linked mod, and Claude Code's copy for any other. A mod also hasdataFolder, and the two are the folders itsmod.folderandmod.dataFoldername. A mod that runs programs as services of this computer also hasservices, their names. A removed mod has onlydataFolder, because its data stays untilcmod teardowndeletes it.The
cmodcommands count a plugin as a mod only when itspackage.jsonhas acmodstep key or cmod holds an install record for it. A mod made withcmod newhas neither until its first Claude Code session sets it up, so until thencmod listshows it asenabled, like any other plugin.
Read your conversations
cmod sessions
cmod sessions list [--every-project] [--since 2d] [--running] [--project <folder>] [--json]
cmod sessions search <text> [--every-project] [--since 2d] [--running] [--project <folder>] [--session <id> [--task <id>] [--turn <id>] [--context <n>] [--agent]] [--limit <n>] [--before <session>:<id>] [--json]
cmod sessions read messages [<session>] [--task <id>] [--turn <id>] [--after <id>] [--last <n>] [--json]
cmod sessions read turns [<session>] [--task <id>] [--context <n>] [--last <n>] [--json]
cmod sessions read contexts [<session>] [--task <id>] [--json]
cmod sessions read tasks [<session>] [--task <id> | --nested] [--json]
cmod sessions read goal [<session>] [--task <id>] [--json]
cmod sessions read usage [<session>] [--task <id>] [--json]
cmod sessions read state [<session>] [--json]
cmod sessions read <part> <session> --transcripts <folder> [--json]
cmod sessions follow [<session>...] [--running] [--json]
cmod sessions indexReads every conversation Claude Code saved, as the sessions, contexts, turns, tasks, and messages sessions answers a mod (session.md), so a person or an agent reads them in a terminal without parsing a transcript. list, search, and read are the sessions, search, and read calls of the cmod/Sessions interface.
listlists the conversations of the current folder's project, or--project's, newest first, each with its time, id, and title.--every-projectlists every project's,--sincekeeps those active in the last30m,6h,2d, or1w, or since a date such as2026-10-01, and--runningkeeps those open in Claude Code now.searchprints the newest 50 messages whose text or tool input contains the text, at least 3 characters, any case, each with its time and session. Each tool input value is searched in its first 1,024 characters, and tool results are not searched.--every-project,--since, and--runningscope it as they scopelist,--limitchanges the 50, and--before <session>:<id>prints the page after the message it names, the last one of the page before.--sessionsearches one conversation, and inside it--tasksearches a task and the tasks it started,--turnone turn,--contextone context, and--agentkeeps the main agent's messages, or with--taskthat task's own, without the tasks it started.read messagesprints one conversation's messages in order: the session named, or the one the command runs in when Claude Code runs it.--taskreads a task's messages instead,--turnkeeps one turn's,--afterstarts after a message id, and--lastkeeps that many from the end.read turnsprints the conversation's turns, each opened by a prompt and closed when Claude finishes.--contextkeeps one context's, and--lastkeeps that many from the end. With--json, a turn names thedeviceit ran on, asTurn.devicedoes (session.md).read contextsprints the conversation's contexts, a new one after each compaction.read tasksprints the tasks the conversation started, with--taskthe tasks that task started, and with--nestedevery task at any depth.read goalprints what the conversation is for: the goal a mod set, or its first prompt.read usageprints the model and the context's tokens as of the last reply.--taskreads theturns,contexts,goal, andusageof the session a task's owner runs, the way they read the conversation's.read stateprints what a running conversation resumes from. It reads the index without writing to it, so it never waits for another cmod that is writing the index.read --transcripts <folder>reads the conversation from the transcripts in<folder>/projects, a Claude Code folder such as one copied from a computer that is off, through an index of its own that lives only while the command runs. So the index of this computer's conversations never lists it, and a mod that serves another device's sessions answerscmod/Sessionsreadin cmod's own shapes. It takes every flag each part takes.followprints each message, turn, context, task, and goal change of the sessions named as Claude Code saves it, until stopped with Ctrl+C.--runningfollows every running session of the project too, and each one that starts later.--jsonprints JSON instead of one line each.indexreads every saved conversation into the index at~/.local/share/cmod/history-13.sqlite, which holds where each message is in its transcript, not a copy of it, and each conversation's turns, with the device each ran on, contexts, and tasks. While cmod has set up a mod other than cmod, the cmod plugin runs it in the background at each session's start, and a second run while one is running exits at once. The index forgets a conversation whose transcript is deleted.
A cmod plugin before 8.0.0 runs cmod history, with sessions for list, each part of read without read, and --all for --every-project, which still works.
cmod ui
cmod ui list <widgets|views|pages> <session>
cmod ui draw <session> <mod> <id> [--columns <n>] [--surface <surface>] [--area <area>]
cmod ui press <session> <handler> [<json>]
cmod ui open <session> <mod> <id>
cmod ui close <session> <mod> <id>
cmod ui show <session> <client> [<mod>/<id>...] [--host]
cmod ui follow [<session>...] [--after <cursor>]Reaches each running session's widgets, views, and pages as an app that draws them does, such as cmod's Herdr mod (ui.md). Each one is a call of the cmod/UI interface (ui.md) through cmod serve, which sends it to the cmod plugin of the session it names, and prints the answer as JSON. A session no cmod plugin on this computer holds fails with No session <session> runs on this computer, so it shows no UI.
listprints the session's widgets, each{ mod, id, areas }, or its views or pages, each{ mod, id, title }.drawprints the widget, view, or page as element data, with each handler as{ "$cmodHandler": <number> }, ornullwhile the mod has not drawn it yet.--columnsis the width it draws in, 80 unless given, and--surfacethe app that draws it:terminal, the default,desktop,mobile,vscode,browser, orherdr.--areais the area a widget shows in, one of the areas it lists:abovePrompt,belowPrompt,working,turnEnd, ordashboard. Without it, a widget draws for the Dashboard when it lists the Dashboard, else for its first area. ForturnEnd, it draws the session's last finished turn, and printsnullbefore the first one finishes.pressruns the handler with that number from one of the part's last two drawings, with the press<json>gives:{ surface, key, kind, value, link }, whosesurfaceisterminalunless it names one.openandcloseshow or take away the view or page in the session's Sidebar.showtells which views and pages one place an app draws in shows, ascmod/UIshowdoes (ui.md), so each one counts asisShownin its mod.<client>names that place, and each part is<mod>/<id>. It replaces that client's last list, a run with no parts clears it, andcmod serveforgets a list 16 seconds after its client's lastshow, so an app runs it again before then.--hostsays the place hosts the session's views, asisHostdoes, and a run with--hostand no parts keeps the host.followprints the next batch ofChange,Redraw,Open, andCloseevents of the sessions named, or of every session, as{ cursor, events, missed }, and exits: at once when events came after the--aftercursor, else on the next event, else after 8 seconds, the timecmod serveanswers each poll within. Each event is{ event: "Change", session, part },{ event: "Redraw", session, mod, id }, or{ event: "Open" or "Close", session, mod, id }for a view or page its mod opened or closed itself, and anOpenthe person asked for carriesisAsked: true. Pass thecursorit printed to--afteron the next run, so a loop that runs it again misses no event.missedis true when the events before the cursor are unknown: on a run without--after, oncecmod servestarted again, or once more events passed thancmod servekeeps, 500 of each. Then read every list and drawing again.
cmod run
cmod run <file> [arguments…]Runs a TypeScript script that reads and drives sessions, for a person or an agent at a terminal. The script imports sessions from @cmodjs/core/mod.js, as a mod does, and cmod run connects it to cmod serve (cmod serve): sessions.list, sessions.get, and sessions.search read every session on this computer and through each sessions provider (session.md), and a session's send, fork, and end reach the session that runs it. A script hears no session, because a listener lives in the session it listens to, as a mod hears only the session it runs in, so its on and before methods throw <script>: <method> works only in a mod's own session. The script also imports provide and providers, which reach the programs that provide interfaces on this computer through the same connection to cmod serve, and a provide answers every session while the script runs (dependencies.md). The script reads its arguments from Bun.argv[2] on. Any other import of mod.js throws a cmod run script imports only sessions, provide and providers from @cmodjs/core/mod.js, because it belongs to a Claude Code session. cmod run ends once the script's top level has run.
import { Prompt, sessions } from '@cmodjs/core/mod.js'
const session = await sessions.get(Bun.argv[2])
const [last] = await session.messages({ last: 1 })
console.log(last?.type === 'reply' ? last.text : session.title)
await session.send({ type: Prompt, text: 'Run the tests again.' })cmod web
cmod webOpens the browser app at http://127.0.0.1:<port>/ and prints that address. The browser app lists every Claude Code session that runs on the computer, in every project, and every running session of each sessions provider, in four groups: Needs you (a permission prompt, a question, or a turn that failed or was stopped), Replied (an answer the person has not opened), Working, and Idle. A session opens its conversation with a prompt box under it, which sends the text as the person's own prompt in that session, a Stop button while it works, and a tab for each of its views, the cmod plugin's Dashboard, History, and Settings among them, and each page open in it, where a press, a text, or a pick runs the mod's handler in that session. j and k move between sessions, Enter opens one and puts the cursor in its prompt box, Esc returns to the list, e marks a reply done, and u marks it unread. A permission prompt or a question is answered in the session's terminal. The browser app runs while Show the Sidebar in your browser is on in Settings, under cmod, Preferences, which open in browser on the Sidebar's key bar turns on and runs this command. When it does not run, cmod web exits 1 and says so. It opens the address by the rule a Button with href follows (ui.md): with the program BROWSER names, else open on macOS and xdg-open on Linux. Over ssh, on Linux with no display, or with BROWSER set to true, it opens nothing, prints the address, and exits 1 with this computer has no browser to open, so open the address above yourself. When the opener fails, it exits 1 after it printed the address. While the browser app is on the person's tailnet (cmod program), it also prints From your other devices: https://<computer>.<tailnet>.ts.net:<port>/, which opens the browser app from each of the person's devices.
Run in an install script
cmod watch
cmod watchTells every running session once a checkout cmod link linked builds after a change, so each one still running the old build offers Reload. It watches each linked folder, outside node_modules and .git, and skips a change to a file git ignores, such as the .claude-plugin/types/ Claude Code writes each time it loads the mod, a change inside the program's output folder, and a change to a file that is gone again and git does not track, such as a build's temporary file. Once a folder has had no change for 2 seconds, it bundles the mod's hooks module as cmod publish does. When a changed file is one the program's build reads, a file in cli/ or one the JavaScript or TypeScript file cli/package.json bin names imports, such as the mod's own src/, it also builds the program cli/ declares and links it as cmod link does, so the program in cmod's programs folder is never older than the mod. A change no program build reads builds no program. A program whose build failed builds again at the next change, whatever it changed. A build that changes the program stops its running copy, so a singleInstance or isService program restarts on the new build (cmod program), and a build that writes the same program leaves the file and the copy as they are. A mod that builds writes the time of its last change to plugins-changed. A session that has not started the mod since then shows the Plugins changed toast once 35 seconds passed since the change and no turn runs, the time Claude Code takes at most to restart a --plugin-dir copy by itself, and no session reloads by itself. A bundle or program build that still fails 10 seconds after the last change shows <mod> does not build with the error as one toast in each session working inside the checkout, the last program that built keeps running, and the toast goes once the mod builds. So an agent's half-written file offers nothing and shows nothing. At its start it bundles again each mod whose failure it finds in build-failures.json, so a failure an older cmod wrote goes once the mod builds. The cmod plugin starts one only in a session that an app shows, once a mod is linked, at the session's start or later, so a device with no linked mod runs none. The first holds watch.lock in the cmod store, watches, and touches its file there every 5 seconds. Another one exits at once while it runs, and the cmod plugin of each such session starts one again once that file is gone or 15 seconds old, so a device runs one watcher however many sessions it has open. Before each touch it reads the newest cmod in the cmod store, the newest version folder of bin/cmod that the launcher runs. A cmod watch older than that exits and lets go of watch.lock, so after a cmod update the new cmod's watcher judges the linked mods by its own rules within 15 seconds. It also exits once the process that started it ends, so a session that crashed leaves no watcher behind.
A cmod before 4.1.0 linked a checkout by writing it into CLAUDE_CODE_PLUGIN_DIRS in the env block of Claude Code's settings.json. cmod watch at its start, and cmod setup, link each folder still in that list as cmod link does now and take it out of the list. A folder that fails to link stays in the list, and its error prints on stderr.
cmod download
cmod download <program> <machine> <url> <sha256> [<machine> <url> <sha256> …]Downloads a program for an install script: fetches the download for this machine, checks its SHA-256, unpacks it, and moves <program> to $CMOD_CACHE/bin/<program>, the mod's cache folder. It links cmod's programs folder and $CMOD_DATA/bin/<program>, where cmod 7 put it, to that file. Before the install step, cmod setup moves each program cmod 7 downloaded to $CMOD_DATA/bin/ there and leaves that link in its place. install-steps.md explains it.
Run from a mod's program
A mod's own program runs outside any session, as one copy per computer or over ssh on a computer with no Claude Code open. These give it what a mod reads in a session.
cmod options
cmod options get <mod> [--project <folder>]... [--json]
cmod options set <mod> <key> <value>get prints a mod's option values in two levels. person holds the values the person set in /config. projects holds the values each project's committed .claude/cmods/<mod>/options.json sets, keyed by the project's git root as git rev-parse --show-toplevel prints it, or by the project's own folder outside git. With no --project, it reads every project cmod's conversation index holds a session of, and lists only those whose options.json exists. It leaves out secrets, and the entries a session would ignore, and names each of those on stderr. A session uses a project's value over the person's, and a value the person's organization locks over both, which this command cannot read outside Claude Code. --json prints { person, projects }:
{ "person": { "<option>": "<value>" }, "projects": { "<project>": { "<option>": "<value>" } } }set sets one option of an installed plugin through claude plugin configure, the way /config sets it, such as cmod options set my-mod branch main. A list option takes its items separated by commas. It refuses a key the plugin's plugin.json userConfig does not declare. A field in Settings and the option questions a mod asks at its first start run it, and the mod reads the new value at its next start (options.md).
A mod built on @cmodjs/core before 8.0.0 runs cmod options <mod> for get and cmod option <mod> <key> <value> for set, and both still work.
cmod device
cmod device [--json]Prints the computer as a mod's device.read() gives it: its id, name, operating system, and architecture (mod.md). It runs the same reader, so a program names each computer by the id its mod sees. --json prints { id, name, os, arch }. On a computer with no machine id, it exits 1 and says so.
cmod data
cmod data [--json]Prints the data folder of each mod cmod set up, the folder its mod.dataFolder names, so a program that moves a person's work to another computer knows what to copy. It reads the mods from the install records in the cmod store, as cmod list does, adds the cmod plugin, which has no install record but keeps each session's goal, tasks, and Log in its data folder, and leaves out a mod whose data folder does not exist. It leaves out each mod.cacheFolder, such as the programs cmod download fetches, because a mod builds that folder again wherever it is missing (mod.md). It leaves out secrets.json, which sits at the root of the cmod store, outside every data folder. It prints one <mod> <folder> line for each mod, and --json prints a list:
[{ "mod": "<mod>", "folder": "<absolute path of its data folder>" }]Run by cmod
cmod runs these itself. A person runs them to see a step's whole log, or to finish a step.
cmod setup
cmod setup <plugin-root> [--events]Refuses a machine the os and cpu keys of the mod's package.json leave out. Downloads the program its cmod.program names, or builds it from the checkout's cli/ when cmod link loaded the mod, so a linked checkout whose version has no release yet still sets up, and links it into cmod's programs folder, which Claude Code runs it from by its name, and into ~/.local/bin unless a file there is not cmod's. Runs the mod's install step, saves its uninstall step, binds its hotkeys, and records the mod as set up, asking nothing first (install-steps.md). Linking a new version stops the running copy of a program the mod runs as one copy or as a service of the computer, so it restarts on the new program, and an install step that fails links the old version back and stops the new one's copy the same way (cmod program). A mod installed from a marketplace whose automatic updates the person has not turned on or off gets them turned on, unless the marketplace is a folder, which Claude Code reads in place, through "autoUpdate": true on the marketplace's extraKnownMarketplaces entry in Claude Code's settings.json, and the setup says so. An unchanged mod runs nothing. --events prints one event per line for a program to read, and the mod's install toast in Claude Code reads them. Before all of that, it links each folder a cmod before 4.1.0 left in CLAUDE_CODE_PLUGIN_DIRS, as cmod watch does.
cmod teardown
cmod teardown <plugin-name> [--events]Runs a removed mod's saved uninstall step, then deletes its install record, the saved step, every version of its program, its data folder, its cache folder, and instances/<plugin-name>/, where its singleInstance and isService programs keep each running copy's pid and address, stops and deletes each service of the computer it runs a program as, with its record and log in services/<plugin-name>/ (cmod program), takes each web app it put on the person's tailnet off it and deletes tailnet/<plugin-name>/, takes out each Claude Code setting it changed that still has the value it set, deletes its secrets (cmod secrets), and deletes its entry in consent.json. It keeps the mod's config folder, ~/.claude/cmods/<plugin-name>. A failed uninstall step keeps the record, so cmod teardown can run again.
cmod hotkeys
cmod hotkeys set <mod | plugin-root> <hotkey> <combo>set binds one hotkey of a mod to a new combo in Claude Code's keybindings.json, such as cmod hotkeys set my-mod toggle ctrl+shift+n, and removes the combo it had. It binds a hotkey without a default combo the same way. A plugin root holds a /, such as ./my-mod, so a mod Claude Code loads with --plugin-dir, which has no install record, binds its hotkeys too. A combo in Settings, under the mod, Hotkeys, runs it, and so does the cmod plugin for its own two hotkeys at its first start, with its own plugin folder. It refuses a combo that is not one, and a combo the person already bound to something else, with <combo> already runs something else in ~/.claude/keybindings.json. Pick another combo. The mod's next update keeps the combo (mod.md). A cmod plugin before 8.0.0 runs cmod hotkey with the same arguments, which still works.
cmod secrets
cmod secrets store <mod> <key>
cmod secrets get <mod> <key>
cmod secrets delete <mod> <key>Keeps a mod's secrets, for mod.secrets and the mod's own programs (mod.md). store reads the value from stdin, such as printf '%s' "$TOKEN" | cmod secrets store my-mod token, and refuses a terminal, where the value would show, and an empty value. get prints the value to stdout as it was stored, with no newline added, and prints nothing for a secret the mod does not have. delete removes one secret. A value never goes in the arguments, where every process on the computer can read it. A mod built on @cmodjs/core before 8.0.0 runs cmod secret with the same arguments, which still works.
Every mod's secrets live as plain values in secrets.json at the root of the cmod store, mode 600, as { "<mod>": { "<key>": "<value>" } }, on every platform and with no keychain. A value cmod 7.0.0 or older sealed on macOS is opened once with the cmod Safe Storage key in the login keychain and written back plain, the first time it is read or the file changes. cmod teardown deletes the secrets of a removed mod.
cmod settings
cmod settings update <mod> <user|project|local> <json> [--project <folder>]update changes Claude Code settings for a set-up mod, as its settings.user.update, settings.project.update, and settings.local.update do (mod.md), such as cmod settings update my-mod user '{"env":{"EDITOR":"vim"}}'. It merges the JSON object into the user, project, or local settings as a JSON Merge Patch: an object merges into the object already there, null removes the key, and an array or any other value replaces it. The project and local settings are those of --project, the current folder when it is left out, and mcpServers in the project settings goes to .mcp.json. cmod keeps every other key and the file's formatting, and cmod teardown takes out each value the mod set that is still the same, then each object that leaves empty. A cmod plugin before 8.0.0 runs cmod settings <mod> <user|project|local> <json>, with no update, which still works.
cmod rules
cmod rules sync [--project <folder>] [--plugin <folder>] [--json]sync links the rules/ folder of each mod that is on into Claude Code's rules folder, and removes the link of each that is off or removed (mod.md). A mod the person installed links at <config>/rules/<mod>, and one turned on only for --project, the current folder when it is left out, links at <project>/.claude/rules/<mod>. It prints the rules it linked. With --json it prints { linked, placed, removed, watched }, where placed and removed name the mods whose link this run made or took away, and watched lists the files and folders whose change can change the next run. --plugin names the cmod plugin's own folder, whose rules/ links for every project, because the cmod plugin has no install record. cmod install, update, remove, enable, disable, setup, teardown, link, and unlink run it after they succeed. The cmod plugin runs it with --plugin when a session starts and before a prompt, each time only when a watched path changed since its last run. A cmod plugin before 8.0.0 runs cmod rules with no sync, which still works.
cmod task
cmod task start <prompt> --title <title> [--clone [--at <message>]] [--agent <type>] [--model <model>] [--cwd <folder>] [--json]Starts a task in a new background Claude Code session, for a mod's startTask with isBackground and its fork with isBackground (session.md). The task belongs to the session Claude Code names in CLAUDE_CODE_SESSION_ID, which the cmod plugin sets when it runs the command. It runs claude --bg on the prompt in --cwd, the current folder when it is left out. With --clone it first writes a fork of that session's conversation as a new transcript beside it, as Claude Code's own fork writes one: each message of the conversation's current branch, from its first through its last, or through the message --at names and nothing after it, each naming the message it copies in forkedFrom. It then runs claude --bg --resume <fork>, so the new session carries on from the copy. --agent and --model pick the agent definition and the model of a fresh session. It finds the new session's id from the 8 characters claude --bg prints, through claude agents --json --all, and passes the starting session and the task in the new session's --settings env, so its cmod plugin tells the starting session at its first stop that the task answered. It saves the task in cmod's data folder, so cmod sessions read tasks of the starting session lists it, with the status claude agents gives it. It prints the task, as one line of JSON with --json.
cmod program
cmod program <mod> [--web-app] [--no-wait | --service [--env <name>]... [--process-type <type>] | --remove-service] -- <command…>Runs one copy of a mod's program for the whole computer, for a program job with singleInstance (jobs.md). The first one takes instances/<mod>/<program>.json.lock in the cmod store, runs the command without CLAUDE_CODE_SESSION_ID, because the copy serves every session, and with CMOD_MOD, the mod's name, and CMOD_PROGRAM, the program's, which connect() reads to provide interfaces (dependencies.md), and CMOD_DATA and CMOD_CACHE, the mod's data and cache folders, which an install step gets too (install-steps.md), writes its first line on standard output, its address, with the copy's pid and start time to instances/<mod>/<program>.json, and prints it. For a program that prints nothing and only provides interfaces through connect(), it writes the copy's pid and start time there, with no address, once cmod serve says the copy provided one, so every command that stops a copy finds both kinds, and prints provided, which the session reads as the copy's start. It asks cmod serve again every 5 seconds while cmod serve is down or starts again. It touches its file in the lock every 5 seconds. With --no-wait, which a mod's session passes, another one touches the holder's file, prints held, and exits 0, and the session reads the address from instances/<mod>/<program>.json and runs cmod program again once that file is gone or the holder's file is 15 seconds old. Without it, as a mod built on @cmodjs/core before 5.3.0 runs it, another one prints the address in that file, then each new one as it changes, and tries the lock again whenever that folder changes and every 5 seconds, so it takes over once the holder exits. A lock whose process is gone counts as free. The holder stops its copy and gives up the lock on SIGTERM, SIGINT, or SIGHUP, and when the session that started it exits, which it checks every 5 seconds. When the copy exits on its own, the holder exits with the copy's exit code, and the copy's standard error passes through. The cmod command that replaces the program's file in the cmod store's programs folder stops the copy itself: cmod setup when it links a new version, or links the old one back after a failed install step, cmod link and cmod watch when a build of the linked checkout changes the program, and cmod download. It sends SIGTERM, then SIGKILL after 5 seconds, to the copy each instances/<mod>/<program>.json names, once its process and start time match, so the copy restarts whatever cmod program holds it, an older one included. The holder then deletes that file and exits with the copy. The session that ran it runs cmod program again a second later, and every other session does too once that file is gone, so one of them starts the new file and the others follow its address. A service's holder exits the same way, and launchd or systemd starts it again. A build with the same bytes, and a link placed again at the same file, leave the program as it was, so the copy keeps running. A new holder that finds a copy an earlier holder left running sends it SIGTERM, then SIGKILL after 5 seconds, and starts its own copy only once that one is gone, so two copies never run at once.
With --service, which a session passes for a program job with isService, it makes the holder a service of the computer named com.claudemodmanager.<mod>.<program>: a launchd agent in ~/Library/LaunchAgents on macOS, loaded into the person's login session, and a systemd user service in ~/.config/systemd/user on Linux, enabled for default.target. Its file is mode 600, because it holds the program's environment. The service runs cmod program <mod> -- <command…> through the cmod store's programs/cmod at login and again whenever it exits, launchd at most once every 10 seconds and systemd 10 seconds after the exit, with HOME, XDG_DATA_HOME, XDG_CACHE_HOME, XDG_CONFIG_HOME, CLAUDE_CONFIG_DIR, and HERDR_APP_HOME as the session has them, so the program reads the same folders the session does, such as its CMOD_DATA and CMOD_CACHE and the Herdr home cmod serve places its Herdr mod in, a PATH of the cmod store's programs folder, /usr/local/bin, /opt/homebrew/bin, /usr/bin, /bin, /usr/sbin, and /sbin, CLAUDE_CODE_EXECPATH, and each --env variable, which the job passes for each key of its environment, PATH included. The PATH is fixed, because sessions started from different shells hold different ones, and a service rewritten for each would restart at every session start. CLAUDE_CODE_EXECPATH names the Claude Code of the session that wrote the service, so a cmod command the program runs finds Claude Code though the PATH holds none. It names the path Claude Code's updates keep, ~/.local/bin/claude when that launcher runs the same install, because the updater deletes old versions and a service rewritten for each version would restart at every update. cmod records it in services/<mod>/<program>.json in the cmod store. On macOS the launchd agent writes the service's standard error, the program's and cmod's own, to services/<mod>/<program>.log beside that record, because launchd keeps no output of its own. Each holder that starts the program first cuts a log over 1 MiB to the whole lines of its last 512 KiB, so a program that fails at every restart, which launchd starts again every 10 seconds, never fills the disk. Linux keeps the program's output in the systemd journal, so the systemd user service writes no log. It holds the mod's lock in the cmod store while it writes and loads the service and waits for it, so sessions that start the mod at once, as every session does after an update, never load it beside each other or beside cmod setup or cmod teardown of the mod. It loads the service when it is new, changed, or not loaded, waits up to 15 seconds for the program to start, prints held, and exits 0, so the session follows the instance file as with --no-wait. The program has started once instances/<mod>/<program>.json names its running copy, which the holder writes when the program prints its address or cmod serve holds an interface its connection provided, so a program that only provides releases the mod's lock at its first provide. A program that has done neither after 15 seconds still counts as started while a holder holds instances/<mod>/<program>.json.lock, so a program slow to listen keeps its service. A service with neither, such as a program that exits at once and whose holder therefore held the lock only for a moment, is stopped, disabled, and deleted with its record, as cmod remove does, and it fails with what shows why: on macOS the service's log in the cmod store, which the removal keeps, and on Linux journalctl --user -u <label>.service. When the computer does not take the service, such as a Linux device without a systemd user session, it deletes what it wrote, says why on standard error, and runs as --no-wait does. When the computer took the service, a loaded launchd agent or an enabled systemd user service, and starting it still failed, such as systemd refusing a program that exited too often, it stops, disables, and deletes the service and its record as cmod remove does, and fails with the service manager's error and what shows why, because the program fails and the person needs that error. The service restarts on a new program as every copy does, and cmod teardown stops and deletes each one.
With --web-app, which a session passes for a program job with isWebApp, the holder puts the copy on the person's tailnet while servesTailnet in preferences.json in the cmod store is on, as it is unless the person turned it off, and tailscale status --json says Tailscale is signed in with HTTPS on. It finds tailscale on its PATH, then at /Applications/Tailscale.app/Contents/MacOS/Tailscale, the macOS app's own copy. It runs the copy with CMOD_TAILNET_NAME, the computer's tailnet name, and CMOD_TAILNET_LOGIN, the login of the computer's owner, and once the copy prints 127.0.0.1:<port>, runs tailscale serve --bg --https=<tailnet port> http://127.0.0.1:<port> before it writes the address, so the instance file carries tailnetUrl, https://<name>:<tailnet port>/, from the moment a session reads it. The tailnet port is the first port the copy listened on, which tailnet/<mod>/<program>.json in the cmod store keeps with the address, or the reason the copy is not on the tailnet, such as Tailscale signed out, HTTPS off, or that port already serving something else on the tailnet, which Settings shows. When the copy exits, the holder runs tailscale serve --https=<tailnet port> off, so no address on the tailnet points at a port the copy left. It stops the copy, which starts again as after any exit, when servesTailnet changes, which it reads every 5 seconds, and when Tailscale becomes ready for a copy that started without it, which it checks every minute. A service passes --web-app on to the cmod program its service runs.
With --process-type, which a session passes for a program job with processType, the launchd agent carries that ProcessType: Interactive runs the program at the priority of an app, where launchd throttles a service with none on a loaded Mac, and Background runs it at the lowest. systemd has no such class, so a Linux service carries none.
With --remove-service, it stops the program's service, deletes its file, its record in services/<mod>/<program>.json, and its log, and exits 0, holding the mod's lock in the cmod store so it never runs beside cmod setup or cmod teardown of the mod. A program with no service changes nothing. A session that starts a mod runs it for each record in services/<mod>/ whose program the mod's setup no longer adds as an isService program, so a new version that dropped isService or renamed the program leaves no service of the old one. A session reads that folder without a process, so a mod with no services/<mod>/ folder runs nothing for it.
cmod serve
cmod serve
cmod web serveServes this computer's sessions to every session, script, and browser on it. The cmod plugin runs it as a service of the computer, com.claudemodmanager.cmod.cmod, of launchd's Interactive class on macOS, because every session waits on it (cmod program). It listens on serve.sock in the cmod store, which only the person can open, and prints unix:<socket> once it listens. cmod web serve runs the same server, for a session whose cmod plugin is from before 7.0.0.
On that socket it answers the cmod/Sessions interface as JSON-RPC (dependencies.md): it lists and reads every session from the conversation index it keeps open, as cmod sessions does, carries each action on a session to the cmod plugin of the session that runs it, and tells a Change for each session that starts or stops running, is visited or deleted, or changes its tasks, goal, or status. It lists each running session's status and waitingFor from Claude Code's record of it, sessions/<pid>.json, which it reads again 300 ms after that folder changes, and adds what only the session's cmod plugin hears: a turn's start and end, the tool call a permission prompt or a question waits on, contextPercent, and lastTurn. It answers a session it does not hold with the not-held code, -32098, and a listener on anything but Change with cmod/Sessions tells only Change, because a mod hears only the session it runs in. It answers the same calls under cmod/SessionStore and cmod/Session, the names a cmod plugin from 7.0.0 calls it by. Each session's cmod plugin holds one connection to it and names its session. It also holds every interface a program on this computer provides through connect(), and carries each call and listener to the connection that provides it, so each session reaches a program through its one connection to cmod serve. A program's providers end with its connection. It reaches a program from a 7.0.0 core, which serves its own wire and names its interfaces as provides in instances/<mod>/<program>.json, by connecting to the address there. It connects to the cmod serve of each device a cmod/Devices provider names, at the address the provider gives, or over the messages the provider carries with its send and Message (dependencies.md), lists that device's providers with its device, and carries each call and listener on one of them there. It offers another device only this computer's providers, and starts a background task whose device names this computer. A Prompt to a session that has ended resumes it with claude --bg --resume, delete deletes an ended session, and visit keeps when each session's reply was last read in visited.json in the cmod store. At its start it deletes each file of the cmod plugin's before folder, where a cmod plugin from before 7.0.0 kept its session's before listeners, whose session no longer runs, and moves web-read.json, the replies cmod web serve before 7.0.0 marked read, to visited.json.
At its start it also places cmod's Herdr mod, which draws every session's widgets, views, and pages in the Herdr app through cmod ui (ui.md), in mods/cmod/ of Herdr's home: $HERDR_APP_HOME, else $XDG_CONFIG_HOME/herdr-app, else ~/.config/herdr-app, when that folder exists. It writes only a file that differs from the one the cmod program carries, records the hash of each file it wrote in herdr.json in the cmod store, and replaces or deletes only a file that still holds what it wrote. A mods/cmod/ folder whose files it did not write stays as it is, and it says so on standard error and places nothing. cmod teardown cmod deletes each file it wrote that still holds what it wrote, and the folder once only what Herdr and the mod write while they run is left in it.
While Show the Sidebar in your browser is on in Settings, under cmod, Preferences, it serves the browser app that cmod web opens, on 127.0.0.1 only, and on the person's tailnet while Tailscale is signed in with HTTPS on. It reads every running session itself: Claude Code's sessions/<pid>.json records, a process counting as running only while its pid runs with the start time Claude Code recorded, and leaving out each sdk-cli process, then each session's transcript through the conversation index. It lists the running sessions of each other sessions provider, another device's cmod serve or a mod's program, beside them, and sends a prompt or a Stop there as that provider's cmod/Sessions send and abort. A session Claude Code records as waiting on a permission prompt or a question moves to Needs you as soon as the dialog opens, and a turn stopped while a command it ran keeps running in the background says so. It reaches each session as every other app does: its status, the permission prompt or question it waits on, how its last turn ended, and its context fill through cmod/Sessions sessions and Change, its views and pages, the cmod plugin's own Dashboard, History, and Settings among them, through cmod/UI with surface: 'browser', which it draws, presses, opens, and closes there and follows by Change, Redraw, Open, and Close, and a prompt or a Stop through cmod/Sessions send and abort. A session whose cmod plugin is older shows only what its transcript says. A cmod plugin from 7.0.0 posts to /api/sessions/<session> and polls /api/sessions/<session>/events, and cmod serve answers the post with {} and the poll after 8 seconds with no views and no actions, so that session warns nothing until it reloads. It keeps web.json in the cmod store with the page's port, and listens on that port again while it is free, so a browser tab left open reconnects after a restart. It refuses a request for any host but 127.0.0.1 and localhost with its port, and a change from any other page. Through the tailnet it answers a request only when its host is CMOD_TAILNET_NAME and its Tailscale-User-Login is CMOD_TAILNET_LOGIN, the person's own, and answers no session call, which comes only through serve.sock. It closes the page once the preference is off, and opens it again when it is on.