install: three delivery channels for the same seven hooks - is the binary channel worth its surface, or is this the plugin's job? #172

New issue

Closed

opened 2026-07-16 22:00:40 +00:00 by hexajon · 2 comments

hexajon commented

2026-07-16 22:00:40 +00:00

(Migrated from codeberg.org)

The seven Claude Code guardrail hooks reach users through three channels today:

The plugin - ships them automatically (with the two skills), installed from the sixfold_space/claude-plugins marketplace: /plugin marketplace add ... then /plugin install madtea@sixfold-plugins.
madtea install - interactively offers them; --hooks is the non-interactive opt-in, --remove-hooks reverses.
madtea mcp-config --install when the target client is Claude Code - the same offer again.

Channels 2 and 3 exist for binary-only users (brew/scoop/tarball) who never add the plugin (binary-channel install): byte-identical scripts, materialized files plus a merge into ~/.claude/settings.json. That is real machinery - install code, removal code, merge logic, drift risk against the plugin copy - duplicated so a user can avoid a plugin whose main job is shipping exactly this payload. Since the marketplace flow landed, the plugin is two slash commands, which weakens the original case for the binary channel.

Decide:

Drop the binary channel; hooks are the plugin's job. The Claude Code wiring path registers the server and recommends the plugin instead of offering hook files. Kills the settings-merge code and the drift surface.
Keep exactly one binary channel - the mcp-config --install offer is the natural survivor (it is already the wiring step); retire madtea install --hooks.
Pin the status quo with a written rationale for why two binary entry points plus the plugin all carry the same payload.

Related: the docs already drifted between channels - clients.md said "six" hooks in four places and still taught the pre-marketplace clone-and-point plugin install; both fixed in the readme-edits batch. Note the plugin does not register the MCP server or ship the binary, so it can never fully replace the wiring step - this issue is only about who delivers the hooks.

The seven Claude Code guardrail hooks reach users through three channels today: 1. **The plugin** - ships them automatically (with the two skills), installed from the `sixfold_space/claude-plugins` marketplace: `/plugin marketplace add ...` then `/plugin install madtea@sixfold-plugins`. 2. **`madtea install`** - interactively offers them; `--hooks` is the non-interactive opt-in, `--remove-hooks` reverses. 3. **`madtea mcp-config --install`** when the target client is Claude Code - the same offer again. Channels 2 and 3 exist for binary-only users (brew/scoop/tarball) who never add the plugin ([binary-channel install](docs/safety/safety-hooks.md#binary-channel-install)): byte-identical scripts, materialized files plus a merge into `~/.claude/settings.json`. That is real machinery - install code, removal code, merge logic, drift risk against the plugin copy - duplicated so a user can avoid a plugin whose main job is shipping exactly this payload. Since the marketplace flow landed, the plugin is two slash commands, which weakens the original case for the binary channel. Decide: - **Drop the binary channel; hooks are the plugin's job.** The Claude Code wiring path registers the server and *recommends the plugin* instead of offering hook files. Kills the settings-merge code and the drift surface. - **Keep exactly one binary channel** - the `mcp-config --install` offer is the natural survivor (it is already the wiring step); retire `madtea install --hooks`. - **Pin the status quo** with a written rationale for why two binary entry points plus the plugin all carry the same payload. Related: the docs already drifted between channels - clients.md said "six" hooks in four places and still taught the pre-marketplace clone-and-point plugin install; both fixed in the readme-edits batch. Note the plugin does not register the MCP server or ship the binary, so it can never fully replace the wiring step - this issue is only about who delivers the hooks.

hexajon commented

2026-07-17 14:58:02 +00:00

(Migrated from codeberg.org)

Need to consolidate any install commands to under madtea install and then flags if users want specific features reinstalled. Bash completion, mcp connection, binary. Right now sprawl is the enemy.

Hooks are the plugin's job, not the binary.

Need to consolidate any install commands to under `madtea install` and then flags if users want specific features reinstalled. Bash completion, mcp connection, binary. Right now sprawl is the enemy. Hooks are the plugin's job, not the binary.

hexajon commented

2026-07-17 16:40:02 +00:00

(Migrated from codeberg.org)

Design pinned for implementation (decision above: hooks are the plugin's job; consolidate setup under install):

The binary hook channel dies entirely: madtea install --hooks/--remove-hooks removed, the interactive hook offer removed from install AND from mcp-config --install, and the hook materialization + settings-merge/removal machinery deleted. Where the offer used to fire, one line recommends the plugin (marketplace add + install) as the way to get the guardrail hooks.
madtea install becomes the one setup command, with feature flags for re-running specific pieces: full run stays the default (binary + completions + MCP registration when the Claude Code CLI is on PATH); granular flags let a user redo one feature (e.g. completions only, MCP registration only) without the full reinstall. Exact flag names follow the existing flag vocabulary; consent flags (--yes-sudo, --yes-delete-stale) unchanged.
mcp-config narrows to the multi-client config surface (print, and install for the other clients whose config files it writes); its Claude Code duties fold into install's MCP step so there is exactly one wiring path for that client.
docs/safety/safety-hooks.md binary-channel section rewritten to point at the plugin; clients guide, COMPARISON rows, reference docs regenerated.
Breaking surface removal (released flags) - next minor per the 0.x tiering, called out in release notes.

Design pinned for implementation (decision above: hooks are the plugin's job; consolidate setup under install): - The binary hook channel dies entirely: `madtea install --hooks`/`--remove-hooks` removed, the interactive hook offer removed from install AND from `mcp-config --install`, and the hook materialization + settings-merge/removal machinery deleted. Where the offer used to fire, one line recommends the plugin (marketplace add + install) as the way to get the guardrail hooks. - `madtea install` becomes the one setup command, with feature flags for re-running specific pieces: full run stays the default (binary + completions + MCP registration when the Claude Code CLI is on PATH); granular flags let a user redo one feature (e.g. completions only, MCP registration only) without the full reinstall. Exact flag names follow the existing flag vocabulary; consent flags (--yes-sudo, --yes-delete-stale) unchanged. - `mcp-config` narrows to the multi-client config surface (print, and install for the other clients whose config files it writes); its Claude Code duties fold into install's MCP step so there is exactly one wiring path for that client. - docs/safety/safety-hooks.md binary-channel section rewritten to point at the plugin; clients guide, COMPARISON rows, reference docs regenerated. - Breaking surface removal (released flags) - next minor per the 0.x tiering, called out in release notes.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#172

No description provided.

Rows
Columns