diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..43cb230 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,217 @@ +# Install Gradata Plugin + +Gradata captures corrections you make to AI coding agent output and graduates +them into durable rules. Over time the agent converges on *your* judgment. + +## Quick install (all platforms) + +```sh +curl -fsSL https://raw.githubusercontent.com/Gradata/gradata-plugin/main/install.sh | sh +``` + +This clones the plugin to `~/.gradata/plugin/`, patches `AGENTS.md`, and +detects which agent CLI(s) you have installed so hooks are wired. + +## Requirements + +- **Python 3.10+** — SDK host (daemon + graduation logic) +- **Node.js 18+** — plugin hooks +- One or more AGENTS.md-aware agent CLIs (see below) +- `pip install git+https://github.com/Gradata/gradata.git#subdirectory=Gradata` (PyPI publish coming soon) + +--- + +## Per-IDE install flows + +### Claude Code + +Claude Code loads Gradata as a plugin via `~/.claude/plugins/gradata`. +The quick install sets this up automatically. Manual setup: + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto +# or install Claude-specific: +node "$HOME/.gradata/plugin/setup/install.js" --agent claude +``` + +**What gets installed:** +- `~/.claude/plugins/gradata` → symlink to `~/.gradata/plugin` +- AGENTS.md Gradata block between `` / `` +- `/gradata status`, `/gradata review`, etc. slash commands + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green +- [ ] In Claude Code: `/gradata doctor` works +- [ ] Start a session, make a correction, end session, wait 24h, check `AGENTS.md` + +--- + +### Codex (OpenAI) + +Codex uses a hook block in `~/.codex/config.toml`. The quick install adds it +automatically. Manual: + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto +# or install Codex-specific: +node "$HOME/.gradata/plugin/setup/install.js" --agent codex +``` + +**What gets installed:** +- `~/.codex/config.toml` — managed hook block between `# BEGIN GRADATA CODEX HOOKS` / `# END GRADATA CODEX HOOKS` +- AGENTS.md Gradata block +- Session lifecycle hooks: start, prompt, edit, stop + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green +- [ ] `cat ~/.codex/config.toml` shows Gradata hook block +- [ ] Start a Codex session — on exit, confirm no error in Gradata daemon logs +- [ ] After ~1h of work, check `~/.gradata/projects/` for lesson files + +--- + +### Cursor + +Cursor uses hooks in `~/.cursor/hooks.json`. + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto +# or install Cursor-specific: +node "$HOME/.gradata/plugin/setup/install.js" --agent cursor +``` + +**What gets installed:** +- `~/.cursor/hooks.json` — managed hook entries +- AGENTS.md Gradata block + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green +- [ ] `cat ~/.cursor/hooks.json` shows Gradata hook entries +- [ ] In Cursor: start session, make a code edit, end session — verify hooks fired + +--- + +### VSCode (via Cline or Continue.dev) + +VSCode does not have a built-in AGENTS.md reader. Use Cline or Continue.dev +(both AGENTS.md-aware extensions) with the Gradata plugin. + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto --patch-agents-md "$PWD/AGENTS.md" +``` + +The `--patch-agents-md` flag targets your project's AGENTS.md (omit for +`~/AGENTS.md`). Cline reads AGENTS.md from the project root automatically. + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green +- [ ] Project AGENTS.md contains a Gradata block +- [ ] In VSCode with Cline: `/gradata-quickstart` loads the Gradata skill +- [ ] Direct hooks (SessionStart, UserPromptSubmit, Stop) are NOT wired — + Cline does not expose lifecycle hooks. Rules inject via AGENTS.md block only. + Graduation sweeps require you to run `node ~/.gradata/plugin/setup/doctor.js` + periodically to trigger the sweep manually. + +--- + +### JetBrains (via Continue.dev) + +JetBrains does not have a built-in AGENTS.md reader. Use Continue.dev +(an AGENTS.md-aware extension) with the Gradata plugin. + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto --patch-agents-md "$PWD/AGENTS.md" +``` + +Same caveats as VSCode: no lifecycle hooks, rules inject via AGENTS.md block +only, graduation sweeps are manual via the doctor command. + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green +- [ ] Project AGENTS.md contains a Gradata block +- [ ] In JetBrains with Continue.dev: Gradata section visible in AGENTS.md context + +--- + +### Hermes / OpenCode / any AGENTS.md-aware CLI + +These runtimes read AGENTS.md automatically — no additional hook wiring needed. + +```sh +git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin" +node "$HOME/.gradata/plugin/setup/install.js" --auto +``` + +The `gradata-quickstart` skill provides the full command reference. Run the +doctor for diagnostics at any time. + +**Post-install checklist:** +- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green + +--- + +## Verify install + +The universal health check works across all IDEs and agent CLIs: + +```sh +node ~/.gradata/plugin/setup/doctor.js +``` + +**Expected output on success:** + +``` +Gradata Doctor +============== +✓ Plugin checkout: ~/.gradata/plugin/ (v0.1.0) +✓ Hooks: 7 hooks present, all parse clean +✓ Node.js: v18+ detected +✓ Python: 3.10+ detected at /usr/bin/python3 +✓ Daemon: reachable on 127.0.0.1:19519 (pid 12345) +✓ AGENTS.md: Gradata block present, markers balanced (1/1) +✓ Config: ~/.gradata/config.toml (python_path set) + +All checks passed. Plugin is healthy. +``` + +If any check fails, the doctor prints specific remediation steps. + +## Troubleshooting + +**"Daemon not available"** +The Python daemon is not running. It auto-starts on session begin. If manually +starting: `gradata daemon start` (or the path in `~/.gradata/config.toml`). + +**"No rules injecting"** +Rules require graduation. A correction must repeat across sessions to reach +PATTERN or RULE tier. New corrections start at INSTINCT and don't inject. + +**"Wrong Python"** +Edit `~/.gradata/config.toml` and update `python_path` to the Python where +the `gradata` package is installed (`which python3`). + +**"Marker corruption in AGENTS.md"** +The installer detected unbalanced `` / `` +markers. Remove both blocks manually and re-run the installer. + +## Uninstall + +```sh +# Remove plugin checkout +rm -rf ~/.gradata/plugin + +# Remove Gradata block from AGENTS.md (between markers) +# Remove Claude Code plugin symlink +rm -f ~/.claude/plugins/gradata + +# Remove Codex hooks (between # BEGIN GRADATA and # END GRADATA in config.toml) +# Remove Cursor hooks (gradata entries in hooks.json) + +# Remove config and data (optional — destroys all lessons) +rm -rf ~/.gradata +```