replay-dispatch

claude-mods

Claude Code mods and a separate Codex adapter for the ai-architect.tools harness. The Claude mods keep one concern per mod, state shared through dependencies:

Audience

Each output of a mod has one reader, and the engine fixes the reader by the API the output goes through (there is no per-call option): $.ui.toast, $.ui.log, $.ui.status, panes and rows are the user's, and the model never sees them; a tool.call result's context, a prompt.submit context and prompt.compose sections are Claude's, and the user never sees them; a deny is the model's tool error (the transcript draws it too). A text is written for its reader, and one string is never sent to both. The mods that send to both say which text is whose:

• zetetic-autopilot: the user reads a toast when main implements (what main ran) and when a subagent spawn is refused (which spawn, how many run, the cap and the window: no instruction); Claude reads, in the context of main's first implementing tool result of a turn, the rule to delegate to a subagent, and, as the Agent tool's error, the cap refusal with the way out (wait for a running agent to finish, spawn again).
• cortex-guard: the user reads a toast for each refusal, for a worktree that was not registered, and for a guard that failed; Claude reads the refusal's rule and fix as the tool's error (the same error when the guard itself failed), and, in the context of the result of its git worktree add, that the worktree was not registered and its cleanup is not covered.
• harness-fleet: the user reads the /fleet pane and its toasts; Claude reads only what a button the user presses puts in front of it (review, take an issue, draft an issue), as "The harness-fleet plugin sent a message: ..." in the plugin's own voice: the owner is "the owner" in it, never "me" or "I".

Developing

Each mod is validated, tested and type-checked on its own:

cd mods/<mod> && claude plugin validate . && claude plugin test && npx -y -p typescript tsc -p . --noEmit

tsc needs the engine to have loaded the mod once (it lays .claude-plugin/types/); keep --noEmit, since a plain tsc -p . writes .js files beside the sources. For hot reload in a session, link the mod into that session's ~/.claude/dev-mods/<session>/ folder; the engine watches the folder a link names.

A mod cannot import a file from another mod (the engine refuses it: "outside the plugin's folder"), so the few small pure files several mods need are copied into each of them: hooks/paths.ts (where ~/ lands: HOME, else USERPROFILE, CLAUDE_CONFIG_DIR for ~/.claude) in five mods, and hooks/design.ts (the one parser of a prompt's DESIGN block) in zetetic-insights and zetetic-autopilot, each with its test. After editing one, copy it over the others; this fails when a copy differs:

sh scripts/check-shared.sh

Installing

.claude-plugin/marketplace.json lists each mod as "source": "./mods/<mod>", so the repository is the marketplace. From another machine:

/plugin install <mod> --marketplace cdeust/claude-mods

y adds the marketplace, then the user scope. On this machine a folder marketplace reads the mods from the checkout, with no copy: claude plugin marketplace add <this folder>, then /plugin install <mod> and /reload-plugins after an edit.

Without write access to settings.json

claude plugin marketplace add and claude plugin install both write enabledPlugins and extraKnownMarketplaces into settings.json. Where that file cannot be changed, load the mods by directory instead: nothing is written, and each mod is registered for the session as <name>@inline.

MODS=/path/to/claude-mods/mods

# repeat --plugin-dir once per mod
claude \
  --plugin-dir $MODS/cortex-guard \
  --plugin-dir $MODS/cortex-wiki \
  --plugin-dir $MODS/zetetic-genius \
  --plugin-dir $MODS/zetetic-autopilot \
  --plugin-dir $MODS/zetetic-insights \
  --plugin-dir $MODS/mission-control \
  --plugin-dir $MODS/harness-fleet

# or one variable, colon separated
CLAUDE_CODE_PLUGIN_DIRS=$MODS/cortex-guard:$MODS/cortex-wiki:$MODS/zetetic-genius:$MODS/zetetic-autopilot:$MODS/zetetic-insights:$MODS/mission-control:$MODS/harness-fleet claude

# an alias in the shell profile: it sets MODS itself, because the alias body is single-quoted and
# is expanded each time it runs, not when the profile is read
alias claude-mods='MODS=/path/to/claude-mods/mods; CLAUDE_CODE_PLUGIN_DIRS=$MODS/cortex-guard:$MODS/cortex-wiki:$MODS/zetetic-genius:$MODS/zetetic-autopilot:$MODS/zetetic-insights:$MODS/mission-control:$MODS/harness-fleet claude'

Which form to prefer: an interactive session may ask for a login when CLAUDE_CONFIG_DIR points at an empty directory (seen once in an isolated directory, where headless claude -p did not ask). On the machine's own configuration directory, which is already logged in, that does not apply; use the repeated --plugin-dir or the alias there, and keep an isolated CLAUDE_CONFIG_DIR for tests only.

claude plugin list shows them under "Session-only plugins" with Status: loaded.

What then must hold:

• The dependencies of a mod are resolved among the mods loaded in the same command, so load a mod together with what it names: zetetic-autopilot needs zetetic-genius; harness-fleet needs cortex-guard, zetetic-autopilot and zetetic-genius. A mod whose dependency is absent is listed disabled, with the error Dependency "<name>" is not installed.
• Options cannot be set (they live in settings.json under pluginConfigs), so every default in a plugin.json has to be right on any machine:

• The machine must let the mods do what they ask: python3 (guard), gh and a route to api.github.com (fleet), the files under ~/.claude/plugins/ (fleet), pandoc and xelatex (wiki), and the model aliases (genius, autopilot).

Measured, on one Mac (Claude Code 2.1.293, no company sandbox): with a pristine settings.json holding {} and an isolated CLAUDE_CONFIG_DIR, loading the mods by CLAUDE_CODE_PLUGIN_DIRS lists them as loaded and leaves settings.json at {}; zetetic-autopilot loaded alone is disabled with the dependency error above.

Not measured: the managed-settings lock itself (it could not be reproduced), whether a company policy accepts --plugin-dir, any refusal of a real sandbox (blocked network, denied exec, unreadable ~/.claude), the model aliases, and whether /config lists the options of directory-loaded mods in an interactive session.