INSTALL.md

Install Gradata Plugin

Pick your IDE below. Each section is self-contained — follow ONE path.

Prerequisites (all IDEs): Git, Node.js 18+, Python 3.10+.

---

1. VSCode

The Gradata plugin runs inside Claude Code's extension for VSCode.

Install

1. Install the Claude Code extension from the VSCode marketplace.

2. Clone the Gradata plugin into Claude Code's plugins directory:

   git clone https://github.com/Gradata/gradata-plugin ~/.claude/plugins/gradata

3. Run the one-time setup script (auto-detects Python, installs gradata SDK if needed):

   node ~/.claude/plugins/gradata/setup/install.js

Verify

Open the Claude Code panel in VSCode (Cmd+Shift+P → "Claude Code: Open") and run:

/gradata doctor

Expected output:

Gradata Doctor
  [+] Daemon running (PID: ...)
  [+] Brain connected
  [+] 7 hooks loaded
  [+] 7 skills registered

If the daemon isn't running, /gradata doctor will start it automatically.

Post-install checklist

• ~/.claude/plugins/gradata/.claude-plugin/plugin.json exists
• ~/.gradata/config.toml has a valid python_path
• gradata Python package is installed (pip list | grep gradata)

---

2. Cursor

Cursor ships Claude Code integration. The plugin install is identical to VSCode.

Install

1. Install Claude Code in Cursor: open the Cursor command palette (Cmd+Shift+P / Ctrl+Shift+P), search "Claude Code", and enable it. (Cursor bundles Claude Code — no marketplace install needed on recent builds.)

2. Clone the plugin:

   git clone https://github.com/Gradata/gradata-plugin ~/.claude/plugins/gradata

3. Run setup:

   node ~/.claude/plugins/gradata/setup/install.js

Verify

In the Claude Code chat panel inside Cursor, run:

/gradata doctor

Expected output matches VSCode: green checkmarks on daemon, brain, hooks, and skills.

Note: activation events

Cursor's Claude Code integration fires the same lifecycle hooks as VSCode — session-start, user-prompt, post-edit, session-stop. If /gradata doctor shows hooks loaded but you don't see rules injecting after corrections, confirm Cursor is running Claude Code ≥ 1.0.37 (check Cmd+Shift+P → "Claude Code: About").

Post-install checklist

• Same three checks as VSCode section above
• Run a correction in Cursor (edit AI output), then /gradata status — lesson count should be ≥ 1

---

3. JetBrains (IntelliJ / PyCharm / WebStorm / GoLand)

Gradata does not yet ship a JetBrains plugin with hook wiring. The Gradata SDK works standalone for manual capture and rule management.

Install

1. Install the Gradata Python SDK:

   pip install gradata

2. (Optional) Set a brain directory if you want project-local storage instead of the default ~/.gradata/:

   export BRAIN_DIR="$HOME/.gradata/brain"

Usage (manual mode)

Without hook wiring, you work with the gradata CLI directly:

# Start the daemon in a terminal tab
gradata daemon --port 7342

# In another tab, capture a correction manually
gradata capture \
  --tool Edit \
  --old 'console.log("x")' \
  --new 'logger.info("x")' \
  --file src/app.ts

# Review lessons and promote
gradata review
gradata promote --id <lesson-id>

# Export rules as markdown for use in JetBrains AI chat / project context
gradata rules --format markdown > .gradata-rules.md

Verify

gradata doctor

Expected output:

Brain Dir     [+]  /home/user/.gradata/brain
Python        [+]  3.12.x
gradata SDK   [+]  1.x.x

Post-install checklist

• gradata --version prints a version
• gradata doctor shows all green checkmarks
• gradata daemon starts without errors (stop with Ctrl+C)

---

Troubleshooting (all IDEs)

"Daemon not available" The Python daemon isn't running or isn't reachable on 127.0.0.1:7342. Run /gradata doctor — it auto-starts the daemon if it's down.

"No rules injecting" Rules require graduation. A correction must repeat across 3+ sessions to reach PATTERN, further to reach RULE. Run /gradata status to check lesson count and tiers.

"Wrong Python" The daemon uses the Python interpreter from ~/.gradata/config.toml. If you installed gradata into a venv, update python_path in that file to point at the venv's interpreter.

"Plugin not loading" (VSCode / Cursor) Check that the plugin directory is correct:

ls ~/.claude/plugins/gradata/.claude-plugin/plugin.json

If missing, the clone didn't land properly. Re-run step 2 of the VSCode/Cursor install.

"node: command not found" Node.js is a prerequisite for the plugin installer and hooks. Install via nvm, fnm, or your system package manager.

---

Next steps

After install, read the README for architecture, commands, and how corrections graduate into rules.