feat(plugin): Claude Code plugin for /plugin install gradata

[Gradata]

Summary

Ships .claude-plugin/plugin.json + hooks/hooks.json so users can install Gradata via Claude Code's plugin marketplace. First-class distribution path matching claude-mem et al.

• .claude-plugin/plugin.json — manifest (name, version, author, homepage, repository, license, keywords) per Claude Code plugin schema
• hooks/hooks.json — wires SessionStart, UserPromptSubmit, PostToolUse (Edit|Write), Stop events to existing gradata.hooks.* modules. No new runtime code.
• .claude-plugin/README.md — prereqs (Python 3.11+, pipx install gradata), install, configure, uninstall, troubleshooting FAQ
• README.md — adds "Claude Code (recommended)" block at top of Quick Start

Hooks reuse inject_brain_rules, context_inject, auto_correct, session_close — the same modules gradata install-hook --ide=claude-code already installs into ~/.claude/settings.json. Plugin is purely additive.

Test plan

• pytest tests/ -x -q passes (2070 passed, 23 skipped)
• JSON validates for both .claude-plugin/plugin.json and hooks/hooks.json
• claude --plugin-dir ./ loads plugin without error (manual, post-merge)
• /plugin marketplace add Gradata/gradata + /plugin install gradata round-trip on a clean machine (manual, after marketplace registration)
• Verify SessionStart hook injects <brain-rules> block when pipx gradata is present and brain has graduated rules

Generated with Gradata

[greptile-apps]

Gradata has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

📝 Walkthrough

Claude Code Plugin Distribution

• New plugin manifest (.claude-plugin/plugin.json): Defines plugin metadata (name: "gradata", version "0.1.0", AGPL-3.0-or-later license) following Claude Code plugin schema
• Hook wiring (hooks/hooks.json): Maps four lifecycle events to existing Gradata modules:
  • SessionStart → injects graduated brain rules (10s timeout)
  • UserPromptSubmit → injects brain context (8s timeout)
  • PostToolUse (Edit|Write actions) → captures tool corrections (5s timeout)
  • Stop → emits session end and runs graduation sweep (15s timeout)
• Plugin documentation (.claude-plugin/README.md): Covers prerequisites (Python 3.11+, pipx install gradata), installation/uninstall, configuration via GRADATA_BRAIN_DIR, hook behavior, and troubleshooting
• README update: Added "Claude Code (recommended)" quick start section linking to plugin marketplace and hook installation paths
• No new runtime code: Plugin is purely additive, reusing existing gradata.hooks.* modules; assumes Gradata is pre-installed

Walkthrough

Added Claude Code plugin configuration and documentation files, including plugin metadata, hook lifecycle definitions, and comprehensive setup/troubleshooting guides. Updated main README with quick-start instructions for plugin installation and advanced SDK setup paths.

Changes

Cohort / File(s)	Summary
Plugin Configuration hooks/hooks.json, .claude-plugin/plugin.json	Introduced plugin metadata (name, version, description, author, license) and hook lifecycle definitions (SessionStart, UserPromptSubmit, PostToolUse, Stop) with associated command bindings and timeouts.
Plugin Documentation .claude-plugin/README.md	Comprehensive plugin documentation covering prerequisites, installation/uninstall commands, hook-to-event mappings, brain directory configuration, troubleshooting steps, and diagnostic guidance.
README Updates README.md	Added quick-start sections for Claude plugin marketplace installation and advanced Python SDK setup path, with links to plugin documentation and prerequisites.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Suggested labels

feature

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a Claude Code plugin for Gradata with plugin marketplace installation support.
Description check	✅ Passed	The description is directly related to the changeset, detailing the four new files (plugin.json, hooks.json, README.md, and README.md updates) and their purpose in enabling Claude Code plugin distribution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/claude-code-plugin

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying gradata-dashboard with    Cloudflare Pages

Latest commit:	8df14b3
Status:	✅  Deploy successful!
Preview URL:	https://27c1cb80.gradata-dashboard.pages.dev
Branch Preview URL:	https://feat-claude-code-plugin.gradata-dashboard.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude-plugin/README.md:
- Around line 24-27: Update the untyped fenced code blocks containing the plugin
CLI commands so they specify the bash language; locate the fences that wrap the
lines with "/plugin marketplace add Gradata/gradata" and "/plugin install
gradata" as well as the fence around "/plugin uninstall gradata" and change the
opening backticks to include "bash" (```bash) so markdownlint no longer flags
them.

In `@hooks/hooks.json`:
- Around line 9-10: Replace the four hook commands that call the package via the
system Python ("python -m gradata.hooks.inject_brain_rules") with the package's
CLI entrypoint so pipx-installed gradata can run them; for each hook in
hooks.json (SessionStart, UserPromptSubmit, PostToolUse, Stop) change the
"command" value from the module invocation to the corresponding CLI form (e.g.,
use "gradata hooks inject-brain-rules" or the equivalent gradata CLI subcommand
for the same hook), keeping the same "timeout" values.

In `@README.md`:
- Around line 41-44: Replace the incorrect top-level command usage in README.md:
the documented command `gradata install-hook --ide=claude-code` is not supported
by the CLI dispatcher; update the example to use the hooks subcommand form (e.g.
`gradata hooks install --ide=claude-code`) so it matches the CLI dispatcher
entry points and will work when copy/pasted.
- Around line 32-35: The fenced command block containing the two plugin commands
(the block with "/plugin marketplace add Gradata/gradata" and "/plugin install
gradata") must be converted to a typed fence for markdownlint and correct
rendering; replace the opening triple backticks with a language identifier
(e.g., change "```" to "```bash") so the block becomes a bash fenced code block.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1cee7fda-af44-48b1-92e4-b20b609b7122

📥 Commits

Reviewing files that changed from the base of the PR and between 25f3546 and 8df14b3.

📒 Files selected for processing (4)

• .claude-plugin/README.md
• .claude-plugin/plugin.json
• README.md
• hooks/hooks.json

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Cloudflare Pages

🧰 Additional context used

🪛 markdownlint-cli2 (0.22.0)

README.md

[warning] 32-32: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

.claude-plugin/README.md

[warning] 24-24: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

[warning] 57-57: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (1)

.claude-plugin/plugin.json (1)

1-19: Metadata payload looks complete and internally consistent.

No correctness concerns in this manifest segment.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add language tags to both command fences.

Lines 24 and 57 use untyped fenced code blocks; markdownlint flags both. Use bash for consistency.

Suggested patch

-```
+```bash
 /plugin marketplace add Gradata/gradata
 /plugin install gradata

...
- +bash
/plugin uninstall gradata

Also applies to: 57-59

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

[warning] 24-24: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude-plugin/README.md around lines 24 - 27, Update the untyped fenced
code blocks containing the plugin CLI commands so they specify the bash
language; locate the fences that wrap the lines with "/plugin marketplace add
Gradata/gradata" and "/plugin install gradata" as well as the fence around
"/plugin uninstall gradata" and change the opening backticks to include "bash"
(```bash) so markdownlint no longer flags them.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

When a package is installed via pipx, does python -m work from the system/default Python by default, or are only console entry-point scripts exposed on PATH?

💡 Result:

When a package is installed via pipx, only console entry-point scripts are exposed on PATH by default. The python -m command does not work from the system/default Python, because pipx installs the package into an isolated virtual environment (typically in ~/.local/share/pipx/venvs/), and the packages in that venv's site-packages are not on the system Python's module search path (sys.path). The entry-point scripts are symlinked to ~/.local/bin (on PATH), and those scripts run using the Python interpreter from the isolated venv, not the system Python.

Citations:

• 1: https://pipx.pypa.io/latest/how-pipx-works/
• 2: https://pipx.pypa.io/latest
• 3: https://pipx.pypa.io/
• 4: https://pipx.pypa.io/stable/comparisons
• 5: https://stackoverflow.com/questions/78229687/what-is-the-difference-between-pipx-and-using-pip-install-inside-a-virtual-envir
• 6: https://packaging.python.org/guides/installing-stand-alone-command-line-tools
• 7: https://pipx.pypa.io/latest/how-to/configure-paths/

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Verify which CLI/hook entry points are defined by this repository packaging.
fd -i 'pyproject.toml|setup.py|setup.cfg' --exec sh -c '
  echo "== $1 ==";
  sed -n "1,260p" "$1"
' sh {}

# Verify available hook-related CLI command surfaces in source.
rg -n --type=py -C3 'cmd_hooks|install_hook|add_parser\("hooks"\)|console_scripts|project\.scripts|entry_points'

Repository: Gradata/gradata

Length of output: 7458

---

🏁 Script executed:

#!/bin/bash
# Read the hooks.json file to verify the exact command format
cat -n hooks/hooks.json 2>/dev/null || echo "File not found"

Repository: Gradata/gradata

Length of output: 1656

---

🏁 Script executed:

#!/bin/bash
# Check if hook modules exist and have __main__.py
find src/gradata/hooks -type f -name "*.py" | sort

# Check for __main__ in hook modules
rg -l "__main__" src/gradata/hooks/ 2>/dev/null || echo "No __main__ found"

Repository: Gradata/gradata

Length of output: 1551

---

🏁 Script executed:

#!/bin/bash
# Examine one of the hook modules to confirm execution pattern
cat -n src/gradata/hooks/inject_brain_rules.py | head -40

Repository: Gradata/gradata

Length of output: 1495

---

🏁 Script executed:

#!/bin/bash
# Check the full content of one hook module to see if it has a main entry point
wc -l src/gradata/hooks/inject_brain_rules.py

# Check if any hook module has if __name__ == "__main__"
rg "if __name__" src/gradata/hooks/

# Verify if cli.py actually has hooks subcommand that could be used instead
sed -n '438,460p' src/gradata/cli.py

Repository: Gradata/gradata

Length of output: 2239

---

Hook commands are incompatible with the documented pipx installation method and will fail silently at runtime.

These commands invoke python -m gradata.hooks.*, which requires the system Python to import gradata. When installed via pipx, the gradata package is isolated to a virtual environment that the system Python cannot access. All four hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop) will fail to execute.

The repository already defines a stable gradata CLI entry point in pyproject.toml that would work reliably after pipx install. Replace the direct module invocations with CLI commands:

Example: SessionStart hook (lines 9-10)

- "command": "python -m gradata.hooks.inject_brain_rules",
+ "command": "gradata hooks inject-brain-rules",

Apply the same fix to lines 21-22, 34-35, and 46-47.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"command": "python -m gradata.hooks.inject_brain_rules",
	"timeout": 10000
	"command": "gradata hooks inject-brain-rules",
	"timeout": 10000

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@hooks/hooks.json` around lines 9 - 10, Replace the four hook commands that
call the package via the system Python ("python -m
gradata.hooks.inject_brain_rules") with the package's CLI entrypoint so
pipx-installed gradata can run them; for each hook in hooks.json (SessionStart,
UserPromptSubmit, PostToolUse, Stop) change the "command" value from the module
invocation to the corresponding CLI form (e.g., use "gradata hooks
inject-brain-rules" or the equivalent gradata CLI subcommand for the same hook),
keeping the same "timeout" values.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add a language identifier to the fenced command block.

Line 32 should use a typed fence (for consistency with markdownlint and rendering).

Suggested patch

-```
+```bash
 /plugin marketplace add Gradata/gradata
 /plugin install gradata

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

[warning] 32-32: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 32 - 35, The fenced command block containing the two
plugin commands (the block with "/plugin marketplace add Gradata/gradata" and
"/plugin install gradata") must be converted to a typed fence for markdownlint
and correct rendering; replace the opening triple backticks with a language
identifier (e.g., change "```" to "```bash") so the block becomes a bash fenced
code block.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Use the actual hooks CLI command path.

Line 43 documents gradata install-hook --ide=claude-code, but the CLI dispatcher evidence points to gradata hooks ... as the supported path. This will cause copy/paste setup failures.

Suggested patch

 pipx install gradata
-gradata install-hook --ide=claude-code
+gradata hooks install

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 41 - 44, Replace the incorrect top-level command
usage in README.md: the documented command `gradata install-hook
--ide=claude-code` is not supported by the CLI dispatcher; update the example to
use the hooks subcommand form (e.g. `gradata hooks install --ide=claude-code`)
so it matches the CLI dispatcher entry points and will work when copy/pasted.