Harness packages¶
What each harness supports for installing brainrc as a native package, without a clone. Research for #50, done 2026-10-08. Formats change fast: re-check a harness's docs before building its package. Gemini CLI was retired for consumer accounts on 2026-06-18; Antigravity CLI replaced it.
At a glance¶
| Harness | Package and install | Rules without a clone | Hooks | Agents | Packs |
|---|---|---|---|---|---|
| Claude Code | .claude-plugin/ (shipped); /plugin install |
SessionStart hook output (10,000-char cap) |
yes: allow, ask, deny | yes, as <plugin>:<name> (gatework:brainrc-work) |
plugin dependencies with semver ranges |
| Codex | .codex-plugin/ or .claude-plugin/ (verified); codex plugin marketplace add owner/repo |
no plugin route: ~/.codex/AGENTS.md or config developer_instructions |
yes: PreToolUse, SessionStart |
TOML roles in config; not shippable in a plugin | separate plugin; no dependencies found |
| Antigravity CLI | root plugin.json (shipped, unverified); agy plugin install <git url> |
plugin rules/*.md with trigger: frontmatter |
yes: PreToolUse ask or deny; no known "no opinion" reply |
markdown, agents/ |
separate plugin; no dependencies found |
| OpenCode | JS plugin (npm or ~/.config/opencode/plugins/): hooks and tools only |
instructions[] config or AGENTS.md |
blocks by throwing; no ask | markdown files with a different frontmatter | plugin[], instructions[], skills.paths |
| Cursor | .cursor-plugin/plugin.json (shipped, unverified); symlink a checkout to ~/.cursor/plugins/local/ |
plugin rules/ with alwaysApply: true |
yes: allow, deny; ask reported broken | markdown, agents/ |
separate plugin; a .cursor-plugin/marketplace.json lists several |
Claude Code¶
Sources: hooks, plugin components, dependencies, plugin CLI.
- Rules: a plugin
SessionStarthook's stdout, orhookSpecificOutput.additionalContext, is added to context. Matchersstartup|resume|clear|compactre-inject after/clearand compaction. Over 10,000 characters, Claude sees a 2,000-character preview only. A plugin-rootCLAUDE.md, rules, and most settings are not loaded.claude plugin validateaccepts the hook (checked here); that the text reaches the model is unconfirmed (needs a live session). - Packs:
"dependencies": [{"name": "brainrc", "version": "^0.3"}]installs core with a pack; versions resolve to git tags<plugin>--v<version>.claude plugin list --jsonlists installed plugins with their paths. A pack skill dispatching a core agent across plugins is unconfirmed. - Hooks from several plugins all run;
deny>ask>allow.
Codex¶
Source: openai/codex at 529cd6b (the docs site was blocked
here): codex-rs/core-plugins/, codex-rs/hooks/, codex-rs/agent-roles/.
- Reads
.claude-plugin/marketplace.jsonand.claude-plugin/plugin.jsonas well as its own.codex-plugin/. Verified with Codex 0.161.0:codex plugin marketplace add <repo>andcodex plugin add brainrc@brainrcinstall our plugin unchanged. Gatework's plugin (brainrc/gatework) works the same way. The install copy drops symlinks (skills/brainrc-gatework/roles), so Gatework falls back to../../agents/. - Skills come from the manifest's
skillsfield when it has one, and only from there, so Gatework's names./skills/as one string, the form Codex's docs give. Core's own plugin has no skills. - Skills: native,
~/.agents/skills(~/.codex/skillsdeprecated). Custom prompts are deprecated for skills; a plugin'scommands/become skills, except any that use$ARGUMENTS(verified: all five of ours were skipped). Core now ships them as user-invoked skills, which Codex installs. - Hooks:
PreToolUse,SessionStart, and more, from a plugin'shooks/hooks.json. Whether aSessionStarthook can inject rules is unconfirmed. - Agents:
[agents.<role>]TOML; a plugin can't ship them.
Antigravity CLI¶
Google's docs site was blocked here and agy (closed source) couldn't be installed, so this
comes from public sources: the antigravity-cli
CHANGELOG and issues (#403, #1053, #1059), and plugins that record tested behavior
(MemPalace,
CoalHearth v2.8.0 on agy 1.3.1).
Nothing here was run against a real agy.
- A plugin is a folder with
plugin.json(its schema requiresnameand rejects unknown keys; askillspath or list adds skill folders toskills/, and nothing names other folders), plus optionalskills/,agents/,rules/,hooks.json, andmcp_config.json.agy plugin install <git url>needsplugin.jsonat the repo root. Nocommands/: skills are the slash commands. Install may copy only the folders it recognises (#403). - Rules:
rules/*.mdload only with frontmatter naming atrigger(always_on,model_decision,glob,manual); files without one are dropped silently. - Hooks:
hooks.jsonat the plugin root,{"<name>": {"PreToolUse": [{"matcher", "hooks"}]}}; commands run from the plugin folder.PreToolUsegetstoolCall: {name, args}(run_command→args.CommandLine;view_file,write_to_file,replace_file_content) and prints{"decision": "ask" | "deny", "reason"}. An empty{}is reported to deny every call andallowis documented as auto-approve, so a guard has no safe reply for "no objection". Not shipped until a live test settles it. - Skills:
disable-slash-commandhides a skill from/;disable-model-invocationis likely ignored.
OpenCode¶
Source: sst/opencode docs source at a697115 (the docs site
was blocked here): packages/web/src/content/docs/.
- A plugin is a JS module: hooks (
tool.execute.before), tools, and system-prompt transforms. It can't ship agent, skill, or command files, so the package is a config dir plus a small plugin. - Agents need a transform (#19, shipped in 0.3.19):
Claude's
tools: Read, Grepmakes OpenCode's whole config invalid (verified, 1.18.35); it wantspermission,modelasprovider/model-id, andmode: subagent. - Guard plugin:
tool.execute.beforecan block by throwing andpermission.askcan answer a prompt OpenCode already shows, but a plugin can't force a prompt, so "ask" becomes "deny". - Skills: native,
~/.config/opencode/skills/(also reads~/.claude/skills/).
Cursor¶
cursor.com is blocked from where this was built, so the format comes from Cursor's official
plugin repo, cursor/plugins (checked 2026-10-09 at ccb5507:
schemas/, its plugins, and its create-plugin scaffold skill), plus hook payload types from the
community cursor-hooks package.
- Manifest:
.cursor-plugin/plugin.json, onlynamerequired, unknown keys rejected.skills,agents,rules,commandstake relative paths;hooksa path or an inline object. Our generated manifest validates againstschemas/plugin.schema.json. - Local install: a plugin directory, or a symlink to one, at
~/.cursor/plugins/local/<name>/. A search result says Cursor falls back to.claude-plugin/when.cursor-plugin/is missing, so we ship our own: Cursor rejects Claude's hook format. - Rules:
description,alwaysApply, optionalglobsfrontmatter; Cursor's examples use.mdc. Whether a plugin loads.mdrules is unconfirmed. - Agents:
name,description,model,readonly. Whether Cursor accepts ourmodel: sonnetvalues is unconfirmed. - Hooks:
{"version": 1, "hooks": {"<event>": [{"command": ...}]}}, user file~/.cursor/hooks.json,${CURSOR_PLUGIN_ROOT}in plugin hooks.beforeShellExecutiongets{command},beforeReadFile{file_path, content}; the reply is{permission, user_message, agent_message}.permission: askwas reported broken in 2.4.21 and reads take only allow or deny.
What this means¶
- One generated
.claude-plugin/serves Claude Code and Codex; Cursor gets.cursor-plugin/. Antigravity needs a rootplugin.json; OpenCode needs a config dir plus a JS hook plugin. - Commands should become skills, or be generated per harness: Codex skips
$ARGUMENTScommands and Antigravity has no commands. - Rules and pack extensions need rendering outside the checkout (
$BRAINRC_HOME), then each harness loads them its own way. Codex plugins have no rules route yet. - Guard hooks need a deny fallback: only Claude Code reliably supports ask.
Proposed order for #50¶
- Render to
$BRAINRC_HOME; Gatework reads extensions from there (every harness needs it). - Codex through the existing
.claude-plugin/: test the install, convert commands to skills. - Antigravity plugin: root
plugin.json, rule triggers (done, unverified); hooks after a live test. - OpenCode: agent transform (#19, done); guard plugin (deny only) done in 0.3.25.
- Cursor:
.cursor-plugin/plugin and guard hooks (deny only) done in 0.3.26; unverified in a real Cursor. - Installable
brainrc(uv tool installorpipx install, from GitHub and later PyPI, core bundled): done in 0.3.22. Packs by git URL, fetched bybrainrc(git+ref,brainrc update): done in 0.3.23.