drogon-claude-plugin

Coding-agent plugin for Drogon C++ backend development — AI-assisted development rules and code-generation skills that keep the assistant writing correct asynchronous code, avoiding classic callback / event-loop pitfalls. Works with Claude Code, ZCode, Codex, Cursor, VS Code (Copilot), Gemini CLI, Qoder, CodeBuddy, Trae and any AGENTS.md-compatible agent on Windows / Linux / macOS.

English | 简体中文

A Claude Code / ZCode plugin for application projects built on the Drogon C++ HTTP framework. It provides AI-assisted development rules and 22 code-generation skills so the assistant produces correct, idiomatic asynchronous code and avoids the frequent traps around callbacks and the event loop.

Installation

Option A: Host-native installation (recommended)

Maintenance tiers: Tier 1 (actively maintained) — Claude Code, ZCode, Codex, Cursor, VS Code + .agents fallback. Best effort — Gemini CLI, Qoder, CodeBuddy, Trae.

Option B: npm / PyPI (CLI installer)

The npm and PyPI packages bundle the exact same plugin assets and expose a single drogon-claude-plugin command. Multi-host installation (--host, scan, instruction-file protection) is implemented in the PyPI CLI (reference implementation); the npm CLI installs the Claude/ZCode bundle (.drogon-plugin/).

# npm — bundle install for Claude Code / ZCode
npx drogon-claude-plugin install

# PyPI — multi-host installer (reference implementation)
pipx install drogon-claude-plugin
drogon-claude-plugin install                 # all hosts (mutual-exclusion aware)
drogon-claude-plugin install --host cursor   # one host
drogon-claude-plugin install --host copilot  # opt-in .agents/skills

Your own files are never touched: if AGENTS.md / GEMINI.md / CODEBUDDY.md already exists, the CLI skips it and prints merge guidance; with --force-agents it appends a <!-- drogon-plugin begin/end --> marker section, and uninstall removes only that section.

Option C: Install from source

git clone https://github.com/voidvec/drogon-claude-plugin
cd <your drogon project>
claude plugin install ../drogon-claude-plugin --scope project

Verify the installation

claude plugin details drogon        # Claude Code
drogon-claude-plugin verify         # CLI installer (works for any host)

You should see 22 skills and 2 hooks (SessionStart + PostToolUse).

The CLI installer

drogon-claude-plugin is published on both npm and PyPI. Both packages ship the same plugin assets and provide the same command-line interface:

What's inside

The plugin is organised in three layers, each with a single responsibility:

Rules layer — CLAUDE.md

A slim-router design: only the discipline that applies to every task (async callback model, event-loop model) plus a skill routing table stay in CLAUDE.md. Everything else — templates, API cheat-sheets, config formats, forbidden patterns — lives in each skill's references/code-guide.md and is loaded on demand, keeping the context window lean.

Top-level discipline covers:

• A. Async callback model — callback exactly once, capture by value, no blocking, prefer coroutines (params by value!), exception-safe
• B. Event-loop model (Trantor IO) — never block the loop, offload heavy work to a thread pool, lock shared state across loops
• General — all I/O async, async ops take two callbacks, no exceptions escape handlers, config loading wrapped in try/catch, strict key names, prefer built-ins (Hodor / PromExporter / AccessLogger), never hand-edit generated code

Code-generation skills (22)

Every skill's references/code-guide.md was written against the drogon v1.9.13 source tree (not just the docs) — where the official docs disagree with the source, the source wins and the difference is called out.

Detection hooks (cross-platform, dependency-free rules injection)

After the assistant edits a file, the PostToolUse hook scans for drogon API violations; the SessionStart hook injects the rules layer. Hook execution is bash-based via a polyglot launcher (hooks/run-hook.cmd, the pattern proven by the superpowers plugin):

• SessionStart is pure shell — no Python, Node or other interpreter required, so rules injection works identically on Windows (Git Bash), Linux and macOS, in both Claude Code and ZCode.
• PostToolUse looks for a Python 3 interpreter (python3 → python → py, overridable via DROGON_PLUGIN_PYTHON) and degrades silently when none exists — it never breaks the host.
• The v0.1.x hooks invoked bare python, which fails silently on Ubuntu 24.04+ (no python binary) and many Windows setups; this is fixed in v0.2.0.

Usage

Once the plugin is enabled in a drogon project it applies automatically. Typical conversations:

> Create a REST controller for /api/users
AI: [uses drogon-create-controller] generates UserController.h + UserController.cc...

> Add a JWT auth filter
AI: [uses drogon-gen-filter] generates JwtAuthFilter.h + the registration call...

> Generate the ORM models from the production schema
AI: [uses drogon-gen-orm-model] writes model.json, runs drogon_ctl create model,
    wires the OBJECT library + orm_compat shim into CMake...

> Write a test for the user registration endpoint
AI: [uses drogon-gen-test] generates a DROGON_TEST(UserRegister) case...

> Is this handler correct?
AI: [consulting CLAUDE.md async discipline] This handler's early-return path never invokes the callback...

Requirements

• Claude Code or ZCode
• A project that depends on the drogon framework (drogon installed as a library)
• Rules injection (SessionStart): works out of the box — needs a bash (Git Bash on Windows is what both hosts already require)
• Violation scanning (PostToolUse): optional, needs a Python 3 interpreter somewhere on the machine

Repository structure

├── .claude-plugin/         # Claude Code manifest + marketplace entry
├── .zcode-plugin/          # ZCode manifest (mirrors .claude-plugin)
├── .github/workflows/
│   ├── ci.yml              # 3-OS matrix: structure + hooks + CLI smoke tests
│   └── publish.yml         # tag-triggered → PyPI + npm + GitHub Release
├── scripts/                # host-artifact generator, asset sync, consistency gate, smoke tests
├── hooks/
│   ├── hooks.json          # SessionStart + PostToolUse registration
│   ├── run-hook.cmd        # cross-platform polyglot launcher
│   ├── session-start       # pure-shell rules injection
│   ├── post-tool-use       # finds a Python 3, degrades gracefully
│   └── posttooluse.py      # violation scanner
├── skills/                 # 22 code-generation skills
├── docs/
│   ├── SKILL-AUTHORING.md  # skill authoring manual (fields, structure, sync checklist)
│   └── PROFESSIONALIZATION-REVIEW.md  # professionalization audit + improvement backlog
├── tests/                  # pytest: scanners, structure, rule fixtures, hook e2e
├── src/drogon_plugin/      # PyPI package (CLI installer)
├── npm/                    # npm package (CLI installer)
├── requirements-dev.txt    # pinned dev/CI dependencies (runtime deps: none)
├── CLAUDE.md               # rules layer
└── CHANGELOG.md

License

MIT — see LICENSE.