Skip to content

Commit e0f90c7

Browse files
MasuRiiMasuRii
committed
docs: add Claude plugin installation research notes
Document findings from Claude Code plugin structure analysis including: - Required plugin directory structure with .claude-plugin/plugin.json - Correct hooks file location in hooks/hooks.json subdirectory - Plugin installation path conventions (~/.claude/plugins/) - Comparison with upstream examples from claude-code repository
1 parent 2b65f4c commit e0f90c7

1 file changed

Lines changed: 243 additions & 0 deletions

File tree

‎docs/research/claude-plugin-installation-2026-03-20.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Research Report: Claude Code Plugin Installation and Verification
2+
3+
> Generated: 2026-03-20 | Researcher Agent
4+
5+
## Executive Summary
6+
7+
The ReCursor project's current approach for installing a Claude Code plugin is **missing critical required components** based on official documentation. The local plugin package (`packages/claude-plugin/`) lacks the mandatory `.claude-plugin/plugin.json` manifest file, and the `hooks.json` file is located at the wrong path (plugin root instead of `hooks/hooks.json`). The installation instructions also reference an incorrect directory path (`~/.claude-code/plugins/` instead of `~/.claude/plugins/` based on upstream examples).
8+
9+
## Source Validation
10+
11+
| Source | Tier | Date | Version/Relevance |
12+
| ------ | ---- | ---- | ----------------- |
13+
| `plugins/plugin-dev/skills/plugin-structure/SKILL.md` | 1 (Official) | Current | Plugin structure requirements |
14+
| `plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md` | 1 (Official) | Current | Minimal plugin requirements |
15+
| `plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md` | 1 (Official) | Current | Standard plugin structure |
16+
| `plugins/plugin-dev/skills/hook-development/SKILL.md` | 1 (Official) | Current | Hook configuration format |
17+
| `plugins/hookify/hooks/hooks.json` | 1 (Official) | Current | Working hookify example |
18+
| `CHANGELOG.md` | 1 (Official) | Current | Installation methods |
19+
| `plugins/plugin-dev/skills/skill-development/SKILL.md` | 1 (Official) | Current | Local testing with `--plugin-dir` |
20+
| `plugins/README.md` | 1 (Official) | Current | High-level plugin overview |
21+
| `plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md` | 1 (Official) | Current | Manifest requirements |
22+
23+
## Key Findings
24+
25+
### 1. Plugin Directory Location (Official Sources)
26+
27+
**Evidence from upstream repository:**
28+
29+
From `C:/Repository/claude-code/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md` (line 548):
30+
```markdown
31+
@/home/user/.claude/plugins/my-plugin/config.json
32+
```
33+
34+
**Finding:** Plugins are cached/installed under `~/.claude/plugins/` (_without_ the `-code` suffix).
35+
36+
**ReCursor Issue:** The ReCursor installation instructions specify `~/.claude-code/plugins/` (with hyphen), which **does not match** the evidenced path pattern.
37+
38+
### 2. Required Plugin Structure (Critical Discovery)
39+
40+
Official Claude Code plugins **must** follow this structure:
41+
42+
```
43+
plugin-name/
44+
├── .claude-plugin/
45+
│ └── plugin.json # REQUIRED: Plugin manifest
46+
├── commands/ # Optional: Slash commands
47+
├── agents/ # Optional: Subagent definitions
48+
├── skills/ # Optional: Agent skills
49+
├── hooks/
50+
│ └── hooks.json # Optional: Event handlers (MUST be in hooks/ subdir)
51+
└── README.md
52+
```
53+
54+
**Source:** `C:/Repository/claude-code/plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md` (lines 1-50)
55+
56+
**Critical finding from manifest-reference.md (line 9):**
57+
> "The manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location."
58+
59+
### 3. The Missing Manifest Problem
60+
61+
**ReCursor's current structure:**
62+
```
63+
packages/claude-plugin/
64+
├── hooks.json # ❌ Wrong location (should be hooks/hooks.json)
65+
└── README.md # Installation docs
66+
```
67+
68+
**Missing:** `.claude-plugin/plugin.json` (REQUIRED)
69+
70+
**The minimal required `plugin.json` (from official source):**
71+
```json
72+
{
73+
"name": "recursor-bridge"
74+
}
75+
```
76+
77+
**Note:** The `name` field must be unique across all installed plugins and use kebab-case (lowercase with hyphens).
78+
79+
### 4. Hooks Configuration Format
80+
81+
**ReCursor's current `hooks.json` is at the plugin root** - this is **wrong**.
82+
83+
**Correct location:** `hooks/hooks.json` (inside a `hooks/` subdirectory)
84+
85+
From `C:/Repository/claude-code/plugins/hookify/hooks/hooks.json`:
86+
```json
87+
{
88+
"description": "Hookify plugin - User-configurable hooks from .local.md files",
89+
"hooks": {
90+
"PreToolUse": [...],
91+
"PostToolUse": [...],
92+
"Stop": [...]
93+
}
94+
}
95+
```
96+
97+
From `C:/Repository/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md`:
98+
> "For plugin hooks in `hooks/hooks.json`, use wrapper format with `hooks` field containing the events"
99+
100+
### 5. Official Installation Mechanisms
101+
102+
**Method A: Marketplace Installation (Production)**
103+
```bash
104+
claude
105+
/plugin install plugin-name@marketplace-name
106+
```
107+
108+
**Method B: Local Development Testing (Development)**
109+
```bash
110+
cc --plugin-dir /path/to/plugin
111+
```
112+
113+
**Source:** `C:/Repository/claude-code/plugins/plugin-dev/skills/skill-development/SKILL.md` (lines 284-288)
114+
115+
**Environment Variables for Plugin Cache:**
116+
- `CLAUDE_CODE_PLUGIN_CACHE_DIR` - Override default plugin cache location
117+
- `CLAUDE_CODE_PLUGIN_SEED_DIR` - For headless mode plugin installation
118+
119+
### 6. Official Verification Steps
120+
121+
**From troubleshooting documentation in `plugins/hookify/README.md`:**
122+
123+
1. **Check plugin is installed:**
124+
```
125+
/plugin
126+
```
127+
(Lists all installed plugins with scope-based grouping)
128+
129+
2. **For hook-specific plugins:**
130+
```
131+
/hookify:list
132+
```
133+
(Lists loaded hook rules - plugin-specific command)
134+
135+
3. **Verify hook triggers:**
136+
- Hooks should work immediately after plugin loads
137+
- No restart of Claude Code required for hooks
138+
- Check rule file exists in correct location
139+
140+
### 7. Hooks vs Plugins vs Skills Clarification
141+
142+
Based on official documentation:
143+
144+
| Term | What It Is | Configuration |
145+
| ---- | ---------- | ------------- |
146+
| **Plugin** | Container for commands, agents, skills, hooks | `.claude-plugin/plugin.json` + optional components |
147+
| **Hooks** | Event-driven automation (PreToolUse, PostToolUse, etc.) | `hooks/hooks.json` in plugin OR direct in `.claude/settings.json` |
148+
| **Skills** | Modular knowledge packages loaded by agents | `skills/skill-name/SKILL.md` |
149+
| **Commands** | Slash commands (`/command-name`) | `commands/command-name.md` |
150+
151+
**Key distinction:** Hooks can exist as user settings (direct in `.claude/settings.json`) OR as plugin components. ReCursor is attempting to distribute hooks as a plugin component.
152+
153+
## Code Examples
154+
155+
### Correct Minimal Plugin Structure for ReCursor
156+
157+
```
158+
recursor-bridge/
159+
├── .claude-plugin/
160+
│ └── plugin.json # Required manifest
161+
├── hooks/
162+
│ └── hooks.json # Hook configuration
163+
└── README.md
164+
```
165+
166+
### Required plugin.json
167+
168+
```json
169+
{
170+
"name": "recursor-bridge",
171+
"version": "1.0.0",
172+
"description": "Forward Claude Code events to ReCursor bridge server"
173+
}
174+
```
175+
176+
### Correct hooks/hooks.json
177+
178+
```json
179+
{
180+
"description": "ReCursor bridge integration - forward events to mobile app",
181+
"hooks": {
182+
"SessionStart": [...],
183+
"SessionEnd": [...],
184+
"PreToolUse": [...],
185+
"PostToolUse": [...],
186+
"Stop": [...],
187+
"UserPromptSubmit": [...],
188+
"Notification": [...],
189+
"SubagentStop": [...]
190+
}
191+
}
192+
```
193+
194+
## Verification Commands
195+
196+
### To Test Locally
197+
```bash
198+
# Navigate to ReCursor project
199+
cd C:/Repository/ReCursor
200+
201+
# Test with --plugin-dir flag
202+
claude --plugin-dir ./packages/claude-plugin
203+
```
204+
205+
### To Verify Installation
206+
```bash
207+
# Inside Claude Code session
208+
/plugin
209+
# Should list "recursor-bridge" among installed plugins if properly structured
210+
```
211+
212+
## Recommendations
213+
214+
1. **Create missing `.claude-plugin/plugin.json`** manifest file (CRITICAL)
215+
2. **Move `hooks.json` to `hooks/hooks.json`** subdirectory (CRITICAL)
216+
3. **Update installation docs** to reference correct path (`~/.claude/plugins/` not `~/.claude-code/plugins/`) (CORRECTION)
217+
4. **Document verification steps**: After installation, run `/plugin` to verify (BEST PRACTICE)
218+
5. **Consider**: If this is hooks-only functionality, distributing via user settings (`.claude/settings.json`) might be simpler than a full plugin (ALTERNATIVE)
219+
220+
## Open Questions (Undocumented Behavior)
221+
222+
| Question | Status | Evidence |
223+
| -------- | ------ | -------- |
224+
| Does copy-install (cp -r) to `~/.claude/plugins/` work without using `/plugin install`? | **Unofficial** | No docs found; `--plugin-dir` is the documented local dev method |
225+
| Is `~/.claude-code/` a valid alternative directory? | **Unverified** | All evidence points to `~/.claude/` (no hyphen) |
226+
| Can hooks.json work at plugin root without subdirectory? | **No** | Official examples always show `hooks/hooks.json` structure |
227+
228+
## References
229+
230+
1. **Claude Code Plugin Development Docs:** `C:/Repository/claude-code/plugins/plugin-dev/skills/plugin-structure/SKILL.md`
231+
2. **Hook Development Docs:** `C:/Repository/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md`
232+
3. **Minimal Plugin Example:** `C:/Repository/claude-code/plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md`
233+
4. **Standard Plugin Example:** `C:/Repository/claude-code/plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md`
234+
5. **Hookify Plugin (Reference Implementation):** `C:/Repository/claude-code/plugins/hookify/`
235+
6. **Official Documentation:** https://docs.claude.com/en/docs/claude-code/plugins (linked in multiple READMEs)
236+
7. **Upstream Repository:** https://github.com/anthropics/claude-code
237+
238+
## Files Modified
239+
240+
None (research-only task)
241+
242+
---
243+
*Generated by Researcher Agent | ReCursor Research Artifact*

0 commit comments

Comments
 (0)