Skip to content

Commit 2bcb536

Browse files
orenlaborenlab
committed
feat(cursor): add Cursor plugin with cross-platform Python hooks
Skills, Rules, Hooks, Agent, MCP server config, docs, and 30 hook tests. Hooks are Python (not bash) for Windows/macOS/Linux support with path traversal defense. Plugin versioned independently (0.1.0).
1 parent 5f7afd7 commit 2bcb536

18 files changed

Lines changed: 1483 additions & 18 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ site/
2828
# IDE
2929
.idea/
3030
.vscode/
31+
.cursor/
3132

3233
# OS
3334
.DS_Store

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ patch against the declared boundary, and generates an auditable review receipt.
4848
| VS Code extension | [Guide](vscode-extension.md) | [Contract](book/21-vscode-extension.md) |
4949
| Claude Desktop bundle | [Guide](claude-desktop-bundle.md) | [Contract](book/22-claude-desktop-bundle.md) |
5050
| Codex plugin | [Guide](codex-plugin.md) | [Contract](book/23-codex-plugin.md) |
51+
| Cursor plugin | [Guide](cursor-plugin.md) | [Contract](book/25-cursor-plugin.md) |
5152

5253
## Reports
5354

@@ -83,6 +84,7 @@ Contract-first documentation derived from code and locked tests.
8384
- [VS Code extension contract](book/21-vscode-extension.md)
8485
- [Claude Desktop bundle contract](book/22-claude-desktop-bundle.md)
8586
- [Codex plugin contract](book/23-codex-plugin.md)
87+
- [Cursor plugin contract](book/25-cursor-plugin.md)
8688
- [Claim Guard](book/28-claim-guard.md)
8789
- [HTML report rendering contract](book/10-html-render.md)
8890

@@ -112,6 +114,7 @@ Contract-first documentation derived from code and locked tests.
112114
- [VS Code extension usage](vscode-extension.md)
113115
- [Claude Desktop bundle usage](claude-desktop-bundle.md)
114116
- [Codex plugin usage](codex-plugin.md)
117+
- [Cursor plugin usage](cursor-plugin.md)
115118
- [SARIF integration](sarif.md)
116119

117120
### Operational

‎docs/book/25-cursor-plugin.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# 25. Cursor Plugin
2+
3+
## Purpose
4+
5+
Document the current contract and behavior of the Cursor plugin sourced from
6+
`plugins/cursor-codeclone/`.
7+
8+
This chapter describes the plugin as a Cursor discovery and AI guidance layer
9+
over existing CodeClone MCP contracts.
10+
11+
!!! note "Guidance layer only"
12+
The plugin contributes discovery metadata, a local MCP definition, skills,
13+
rules, hooks, and an agent definition. It does not add a second analyzer or
14+
Cursor-only finding semantics.
15+
16+
## Position in the platform
17+
18+
The Cursor plugin is:
19+
20+
- sourced from `plugins/cursor-codeclone/` in this monorepo
21+
- backed by the Cursor Plugin manifest at `.cursor-plugin/plugin.json`
22+
- read-only with respect to repository state
23+
- a composition of local MCP server metadata, AI skills, rules, hooks, and an
24+
agent definition
25+
- a native Cursor setup surface, not a second extension model
26+
27+
## Source of truth
28+
29+
The plugin delegates analysis to the existing `codeclone-mcp` launcher and
30+
guides AI agent usage through bundled skills and rules.
31+
32+
New canonical MCP surfaces flow through from the resolved local server version.
33+
That includes current-run metric families such as `Coverage Join` and the
34+
optional `coverage` help topic when that server supports them.
35+
36+
It must not:
37+
38+
- run a second analysis engine
39+
- redefine findings, health, or gates
40+
- mutate source files, baselines, cache, or report artifacts
41+
- drift away from canonical MCP semantics
42+
43+
## Current surface
44+
45+
The plugin currently provides:
46+
47+
- `.cursor-plugin/plugin.json` — plugin manifest
48+
- `mcp.json` — local stdio MCP server definition
49+
- five bundled skills:
50+
- `codeclone-production-triage` — fast production-focused first pass
51+
- `codeclone-hotspots` — quick health snapshot
52+
- `codeclone-blast-radius` — standalone structural impact inspection
53+
- `codeclone-review` — full structural review session
54+
- `codeclone-change-control` — intent-first change workflow
55+
- one agent:
56+
- `structural-reviewer` — deterministic code reviewer backed by MCP tools
57+
- two rules:
58+
- `codeclone-workflow.mdc` — MCP discipline (always active)
59+
- `codeclone-python.mdc` — Python file context (glob-triggered)
60+
- two hooks:
61+
- `afterFileEdit` — post-edit re-analysis reminder
62+
- `stop` — session-end intent cleanup check
63+
64+
## Runtime model
65+
66+
The plugin surface is additive:
67+
68+
- `mcp.json` contributes a local stdio MCP server definition
69+
- the skills contribute workflow guidance and starter prompts
70+
- the rules enforce MCP-first discipline and Python-aware context
71+
- the hooks provide automated reminders for re-analysis and intent hygiene
72+
- the agent provides a structured review protocol backed by MCP tools
73+
- Cursor remains free to use direct MCP configuration alongside or instead of
74+
the plugin
75+
76+
The plugin does not rewrite user config or install CodeClone automatically.
77+
78+
## Skill contract
79+
80+
Each skill follows these invariants:
81+
82+
- **MCP tools only** — no fallback to CLI or local report files
83+
- **Absolute roots** — analysis tools receive absolute repository paths
84+
- **Source of truth** — CodeClone findings are reported as-is, not reinterpreted
85+
- **Conservative first pass** — default thresholds unless the user explicitly
86+
asks for a deeper review
87+
- **Scope discipline** — change control skills enforce declare/check/verify/clear
88+
89+
Skills are invocable via `/skill-name` in Cursor chat. Each skill's `SKILL.md`
90+
contains the full workflow, rules, and non-goals.
91+
92+
## Hook contract
93+
94+
Hooks follow these invariants:
95+
96+
- **Non-blocking** — hooks return quickly (5-second timeout) and do not block
97+
agent execution
98+
- **Advisory only** — hooks return `followup_message` suggestions, not
99+
mandatory actions
100+
- **Deterministic** — hooks use simple pattern matching, not heuristic analysis
101+
- **Fail-open** — hook failures do not prevent the agent from continuing
102+
103+
## Agent contract
104+
105+
The structural reviewer agent:
106+
107+
- uses CodeClone MCP tools exclusively for evidence
108+
- does not modify files or declare change intent
109+
- does not suppress or dismiss findings
110+
- does not treat report-only signals as CI failures or vulnerability claims
111+
- reports with file paths, finding IDs, and severities from CodeClone
112+
113+
## Design rules
114+
115+
- **Cursor-native packaging**: keep source under `plugins/cursor-codeclone/`
116+
and use `.cursor-plugin/plugin.json` as the manifest.
117+
- **Canonical MCP first**: all analysis flows through `codeclone-mcp`.
118+
- **Skill guidance, not analysis logic**: skills teach CodeClone workflows but
119+
do not create new findings.
120+
- **Rule discipline**: rules enforce MCP-first usage and prevent fallback to
121+
CLI or manual reinterpretation.
122+
- **Hook safety**: hooks are advisory, non-blocking, and fail-open.
123+
- **Agent honesty**: the structural reviewer reports deterministic evidence, not
124+
opinions.
125+
- **No hidden installation side effects**: the plugin does not patch Cursor
126+
settings or install binaries.
127+
- **Launcher honesty**: the plugin assumes `codeclone-mcp` is already
128+
installable in the current workspace or reachable on `PATH`.
129+
130+
## Relationship to other interfaces
131+
132+
- CLI remains the scripting and CI surface.
133+
- MCP remains the cross-client integration contract.
134+
- VS Code extension remains the native IDE view surface.
135+
- Codex plugin remains the Codex-native discovery surface.
136+
- The Cursor plugin is the native Cursor AI discovery and governance layer for
137+
CodeClone.
138+
139+
## Non-guarantees
140+
141+
- Cursor plugin UI presentation and skill discovery may evolve independently
142+
of the plugin manifest content.
143+
- Users who already configured `codeclone-mcp` manually may prefer the direct
144+
MCP path over the bundled plugin MCP definition.
145+
- Hook behavior may be refined as Cursor's hook API evolves.

‎docs/book/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ If a statement is not enforced by code/tests, it is explicitly marked as non-con
3737
- [21-vscode-extension.md](21-vscode-extension.md)
3838
- [22-claude-desktop-bundle.md](22-claude-desktop-bundle.md)
3939
- [23-codex-plugin.md](23-codex-plugin.md)
40+
- [25-cursor-plugin.md](25-cursor-plugin.md)
4041
- [24-structural-change-controller.md](24-structural-change-controller.md)
4142
- [10-html-render.md](10-html-render.md)
4243

‎docs/cursor-plugin.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Cursor Plugin
2+
3+
CodeClone ships a native Cursor plugin. Source lives in
4+
`plugins/cursor-codeclone/`; the plugin bundles an MCP server definition,
5+
five skills, one agent, two rules, and two hooks.
6+
7+
## What ships in the plugin
8+
9+
| Component | Path | Purpose |
10+
|-----------|------|---------|
11+
| `.cursor-plugin/plugin.json` | Manifest | Plugin metadata and component declarations |
12+
| `mcp.json` | MCP server | Local stdio `codeclone-mcp` server definition |
13+
| `skills/codeclone-review/` | Skill | Conservative-first full structural review |
14+
| `skills/codeclone-hotspots/` | Skill | Quick hotspot discovery and health snapshot |
15+
| `skills/codeclone-change-control/` | Skill | Intent-first change workflow with blast radius and verification |
16+
| `skills/blast-radius/` | Skill | Standalone blast radius inspection before edits |
17+
| `skills/production-triage/` | Skill | Fast production-focused triage and next-action recommendation |
18+
| `agents/structural-reviewer.md` | Agent | Deterministic structural code reviewer backed by MCP tools |
19+
| `rules/codeclone-workflow.mdc` | Rule | MCP workflow discipline (always active) |
20+
| `rules/codeclone-python.mdc` | Rule | Python file context (auto-triggers on `**/*.py`) |
21+
| `hooks/hooks.json` | Hooks | Post-edit re-analysis reminder and session cleanup check |
22+
| `assets/` | Branding | Plugin logo and icon |
23+
24+
## Install
25+
26+
The plugin expects a local `codeclone-mcp` launcher. Install CodeClone with
27+
the MCP extra:
28+
29+
```bash
30+
uv tool install "codeclone[mcp]"
31+
codeclone-mcp --help
32+
```
33+
34+
### Project-level setup
35+
36+
Symlink the plugin into the project `.cursor/` directory:
37+
38+
```bash
39+
mkdir -p .cursor/skills .cursor/rules .cursor/agents
40+
41+
# Skills
42+
for d in plugins/cursor-codeclone/skills/*/; do
43+
ln -sfn "$(pwd)/$d" ".cursor/skills/$(basename $d)"
44+
done
45+
46+
# Rules
47+
for f in plugins/cursor-codeclone/rules/*.mdc; do
48+
ln -sfn "$(pwd)/$f" ".cursor/rules/$(basename $f)"
49+
done
50+
51+
# MCP server
52+
ln -sfn "$(pwd)/plugins/cursor-codeclone/mcp.json" .cursor/mcp.json
53+
54+
# Agent
55+
ln -sfn "$(pwd)/plugins/cursor-codeclone/agents/structural-reviewer.md" \
56+
.cursor/agents/structural-reviewer.md
57+
```
58+
59+
Add `.cursor/` to `.gitignore` if it is not already there.
60+
61+
### Personal (global) setup
62+
63+
```bash
64+
ln -sfn /path/to/codeclone/plugins/cursor-codeclone \
65+
~/.cursor/plugins/local/codeclone
66+
```
67+
68+
## Skills
69+
70+
### codeclone-production-triage
71+
72+
Fast production-focused first pass: health score, finding counts, top hotspots,
73+
baseline status, and recommended next action. Two MCP calls:
74+
`analyze_repository` then `get_production_triage`.
75+
76+
### codeclone-hotspots
77+
78+
Quick quality snapshot: health check, top risks, single-metric queries. The
79+
cheapest useful path for answering ad-hoc questions about repository quality.
80+
81+
### codeclone-blast-radius
82+
83+
Standalone blast radius inspection before editing files. Shows dependents,
84+
clone cohort, risk signals, do-not-touch boundaries, and guardrails. Read-only
85+
— does not declare intent or start a change workflow.
86+
87+
### codeclone-review
88+
89+
Full structural review: clone triage, changed-scope review, health-oriented
90+
refactor planning. Starts conservative with default thresholds, supports
91+
deeper follow-up with lowered thresholds and run comparison.
92+
93+
### codeclone-change-control
94+
95+
Intent-first change workflow for repository edits. Declares scope before
96+
editing, maps blast radius, verifies the patch against the contract, generates
97+
a review receipt, and validates cited review claims. This is the governance
98+
skill — use it whenever the task requires changing files.
99+
100+
## Agent
101+
102+
### structural-reviewer
103+
104+
Deterministic structural code reviewer that uses CodeClone MCP tools to assess
105+
clone risk, complexity hotspots, coupling, and blast radius. Reports findings
106+
with file paths and evidence, not opinions. Does not modify files or declare
107+
intent.
108+
109+
## Rules
110+
111+
- **codeclone-workflow.mdc** (always active) — MCP workflow discipline: use MCP
112+
tools only, pass absolute roots, prefer `get_production_triage` after
113+
analysis, do not fall back to CLI or local report files.
114+
- **codeclone-python.mdc** (glob: `**/*.py`) — auto-triggers when Python files
115+
are in context: run analysis before structural changes, check blast radius,
116+
do not introduce regressions.
117+
118+
## Hooks
119+
120+
- **afterFileEdit** — when a Python file is edited, reminds the agent to
121+
re-run analysis and check intent status.
122+
- **stop** — at session end, warns if change intents were declared but not
123+
cleared.
124+
125+
## Runtime model
126+
127+
Additive — the plugin provides a local MCP definition, five skills, one agent,
128+
two rules, and two hooks. New canonical MCP surfaces from the local
129+
`codeclone-mcp` version flow through directly. The plugin does not install a
130+
second server binary or mutate Cursor settings.
131+
132+
## Current limits
133+
134+
- If you already configured `codeclone-mcp` manually in Cursor MCP settings,
135+
keep only one setup path to avoid duplicate MCP surfaces.
136+
- The bundled `mcp.json` expects `codeclone-mcp` on `PATH` or configured with
137+
an absolute path.
138+
- Hooks use shell scripts and require `bash` and `grep`.
139+
140+
## Further reading
141+
142+
- [MCP usage guide](mcp.md)
143+
- [MCP interface contract](book/20-mcp-interface.md)
144+
- [Structural Change Controller](book/24-structural-change-controller.md)
145+
- [Cursor plugin contract](book/25-cursor-plugin.md)

‎plugins/cursor-codeclone/.cursor-plugin/plugin.json‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
{
22
"name": "codeclone",
3-
"version": "2.1.0a1",
4-
"description": "Baseline-aware structural code quality analysis for Cursor through the local CodeClone MCP server.",
3+
"displayName": "CodeClone",
4+
"version": "0.1.0",
5+
"description": "Structural Change Controller for AI-assisted Python development. Deterministic structural review, baseline-aware CI gates, and explicit change boundaries for coding agents — powered by codeclone-mcp.",
56
"author": {
67
"name": "Den Rozhnovskiy",
7-
"email": "pytelemonbot@mail.ru",
8-
"url": "https://github.com/orenlab"
8+
"email": "roghnovskiy@gmail.com"
99
},
10-
"homepage": "https://orenlab.github.io/codeclone/cursor-plugin/",
10+
"publisher": "orenlab",
11+
"homepage": "https://orenlab.github.io/codeclone/",
1112
"repository": "https://github.com/orenlab/codeclone",
1213
"license": "MPL-2.0",
14+
"logo": "assets/logo.png",
1315
"keywords": [
1416
"codeclone",
1517
"cursor",
@@ -18,10 +20,20 @@
1820
"baseline-aware",
1921
"code-quality",
2022
"clone-detection",
23+
"blast-radius",
2124
"python"
2225
],
23-
"rules": "rules/",
26+
"category": "developer-tools",
27+
"tags": [
28+
"python",
29+
"analysis",
30+
"review",
31+
"refactoring",
32+
"mcp"
33+
],
2434
"skills": "skills/",
25-
"mcpServers": "mcp.json",
26-
"logo": "assets/logo.png"
35+
"agents": "agents/",
36+
"rules": "rules/",
37+
"hooks": "hooks/hooks.json",
38+
"mcpServers": "mcp.json"
2739
}

‎plugins/cursor-codeclone/CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Change Log
2+
3+
## 0.1.0
4+
5+
- initial Cursor plugin for CodeClone
6+
- 5 skills: production triage, hotspots, blast radius, review, change control
7+
- 1 agent: structural reviewer with deterministic CodeClone-backed assessment
8+
- 2 rules: MCP workflow discipline (always), Python file context (glob)
9+
- 2 hooks: post-edit re-analysis reminder, session-end intent cleanup check
10+
- MCP server bundle for `codeclone-mcp` over stdio

0 commit comments

Comments
 (0)