|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +This is a Claude Code plugin marketplace repository providing bundled plugins that extend Claude Code with specialized tools and automation. The repository contains: |
| 8 | + |
| 9 | +- **Marketplace Configuration**: Managed via `.claude-plugin/marketplace.json` |
| 10 | +- **Plugin Collection**: Multiple plugins in `plugins/` directory (nanobanana, security, flutter, code-review) |
| 11 | +- **Web Application**: Nuxt-based marketplace frontend in `apps/web/` |
| 12 | +- **Hooks System**: Session initialization hooks in `hooks/` |
| 13 | + |
| 14 | +## Architecture |
| 15 | + |
| 16 | +### Plugin Structure |
| 17 | + |
| 18 | +Each plugin follows this standard structure: |
| 19 | +``` |
| 20 | +plugins/<plugin-name>/ |
| 21 | +├── gemini-extension.json # Plugin manifest |
| 22 | +├── README.md # Plugin documentation |
| 23 | +├── commands/ # Slash commands (markdown files) |
| 24 | +├── hooks/ # Hook configurations |
| 25 | +└── mcp-server/ # MCP server implementation |
| 26 | + ├── package.json |
| 27 | + ├── src/ |
| 28 | + │ ├── index.ts # Main server entry |
| 29 | + │ └── *.ts # Implementation modules |
| 30 | + └── dist/ # Compiled output |
| 31 | +``` |
| 32 | + |
| 33 | +### Key Components |
| 34 | + |
| 35 | +**1. gemini-extension.json** |
| 36 | +- Defines plugin metadata (name, version, description) |
| 37 | +- Configures MCP servers with command and args |
| 38 | +- Specifies context file (usually `GEMINI.md`) |
| 39 | + |
| 40 | +**2. MCP Servers** |
| 41 | +- Node.js-based servers using `@modelcontextprotocol/sdk` |
| 42 | +- Compiled TypeScript from `mcp-server/src/` to `mcp-server/dist/` |
| 43 | +- Run via `node mcp-server/dist/index.js` |
| 44 | + |
| 45 | +**3. Commands** |
| 46 | +- Markdown files in `commands/` directory |
| 47 | +- Define slash commands accessible in Claude Code |
| 48 | +- Command names derived from file structure (e.g., `commands/security/analyze.md` → `/security:analyze`) |
| 49 | + |
| 50 | +**4. Hooks** |
| 51 | +- `hooks.json` files define event-driven automation |
| 52 | +- Common hooks: `SessionStart`, `PostToolUse` |
| 53 | +- Can execute shell commands or load context |
| 54 | + |
| 55 | +### Web Application |
| 56 | + |
| 57 | +The marketplace website is built with: |
| 58 | +- **Framework**: Nuxt 4 (Vue 3) |
| 59 | +- **UI**: Nuxt UI v4 |
| 60 | +- **Content**: Nuxt Content for markdown pages |
| 61 | +- **Database**: better-sqlite3 |
| 62 | +- **Node**: Version 22.x (specified in `.nvmrc`) |
| 63 | + |
| 64 | +## Common Commands |
| 65 | + |
| 66 | +### Web Application |
| 67 | +```bash |
| 68 | +# Navigate to web app |
| 69 | +cd apps/web |
| 70 | + |
| 71 | +# Install dependencies |
| 72 | +npm install |
| 73 | + |
| 74 | +# Development server |
| 75 | +npm run dev |
| 76 | + |
| 77 | +# Build for production |
| 78 | +npm run build |
| 79 | + |
| 80 | +# Preview production build |
| 81 | +npm run preview |
| 82 | + |
| 83 | +# Generate static site |
| 84 | +npm run generate |
| 85 | +``` |
| 86 | + |
| 87 | +### Plugin Development |
| 88 | + |
| 89 | +Each plugin is maintained in its own repository. For plugin-specific development commands and setup, refer to each plugin's repository: |
| 90 | +- `plugins/nanobanana/` → https://github.com/pleaseai/nanobanana |
| 91 | +- `plugins/security/` → https://github.com/pleaseai/security-plugin |
| 92 | +- `plugins/flutter/` → https://github.com/pleaseai/flutter |
| 93 | +- `plugins/code-review/` → https://github.com/pleaseai/code-review-plugin |
| 94 | +- `plugins/spec-kit/` → https://github.com/pleaseai/spec-kit-plugin |
| 95 | + |
| 96 | +## Development Standards |
| 97 | + |
| 98 | +This project follows strict development standards documented in: |
| 99 | +- @docs/commit-convention.md |
| 100 | +- @docs/STANDARDS.md |
| 101 | +- @docs/TDD.md |
| 102 | +- @docs/TESTING.md |
| 103 | + |
| 104 | +## Plugin Installation |
| 105 | + |
| 106 | +Users can add this marketplace and install plugins: |
| 107 | + |
| 108 | +```bash |
| 109 | +# Add marketplace |
| 110 | +/plugin marketplace add pleaseai/claude-code-plugins |
| 111 | + |
| 112 | +# Install a plugin |
| 113 | +/plugin install nanobanana@pleaseai |
| 114 | +/plugin install gemini-cli-security@pleaseai |
| 115 | +``` |
| 116 | + |
| 117 | +## Testing Commands |
| 118 | + |
| 119 | +```bash |
| 120 | +# For plugins with tests |
| 121 | +cd plugins/<plugin-name> |
| 122 | +npm run test |
| 123 | + |
| 124 | +# Type checking across plugins |
| 125 | +npm run typecheck |
| 126 | +``` |
| 127 | + |
| 128 | +## Key Files |
| 129 | + |
| 130 | +- `.claude-plugin/marketplace.json` - Marketplace configuration and plugin registry |
| 131 | +- `apps/web/nuxt.config.ts` - Nuxt application configuration |
| 132 | +- `plugins/*/gemini-extension.json` - Plugin manifests |
| 133 | +- `hooks/hooks.json` - Session start hooks |
| 134 | +- `docs/commit-convention.md` - Commit message guidelines |
| 135 | +- `docs/TDD.md` - Test-driven development methodology |
| 136 | +- `.nvmrc` - Node.js version specification (v22) |
| 137 | + |
| 138 | +## Notes |
| 139 | + |
| 140 | +- This repository serves as both a plugin marketplace and a collection of plugin implementations |
| 141 | +- Each plugin can be independently versioned and released |
| 142 | +- MCP servers provide the runtime interface between Claude Code and plugin functionality |
| 143 | +- Plugins are designed to be easily toggled on/off by users |
0 commit comments