@hatchworksai/stella-cursor-install

Install Cursor IDE hooks and git hooks for Stella so developer activity is sent to your Stella dashboard.

Usage

From your project root (a git repo):

npx @hatchworksai/stella-cursor-install --project-code <code> --token <token> --url <url>

Parameters:

• --project-code: Your repository's project code (e.g. GN, GVH) from the Stella dashboard
• --token: A one-time installation token generated from the Stella dashboard (repository setup guide)
• --url: The full cursor-history endpoint URL (e.g. https://stella-dev-nextjs-gue66h5uyq-uc.a.run.app/api/cursor-history)

You can obtain the project code, token, and URL from the repository setup guide in the Stella dashboard when you first access a repository.

Mirror scripts: The installer copies these files from stella-cursor-install/hooks/. When you change any script in .cursor/hooks/ in this repo, update the same file under stella-cursor-install/hooks/ so the published installer stays in sync.

| Script | Purpose | |--------|---------| | clear-events-after-push.js | Clears event CSVs after pre-push upload | | log-after-agent-response.js | Logs agent response timestamps to after-agent-response.csv | | log-before-submit-prompt.js | Logs prompt submit timestamps to before-submit-prompt.csv | | log-edits.js | Logs file edits for Cursor edit events | | log-session.js | Session logging (sessionStart/sessionEnd); writes .cursor/events/sessions.csv with session type (agent | ask | edit) | | post-commit.js | Writes commit history (.cursor/history/<sha>.json) and the full upload payload (.cursor/history/<sha>-payload.json) for debugging | | upload-history.js | On pre-push, reads .cursor/history/*-payload.json and POSTs each; payload sent is the same as the file written at commit time |

The installer will:

• Validate the installation token with the Stella API
• Create .cursor/hooks/ with the scripts in the table above
• Create .cursor/hooks.json so Cursor runs the hooks
• Create .cursor/hooks/upload-config.json with the provided API URL and project code
• Install git hooks: post-commit (writes commit history and payload file for debugging) and pre-push (uploads payload files to Stella)
• Add Cursor-related entries to .gitignore if not already present (so .cursor/events/, .cursor/history/, and upload-config.json are not committed)

After each commit, .cursor/history/<sha>-payload.json contains the exact request body that will be sent on the next push, so you can inspect sessions and duration before pushing.

Requirements

• Node.js 18+
• Git (for git hooks)
• A repository already added in Stella dashboard
• An installation token generated from the repository setup guide in the Stella dashboard

Verifying that CSV events are written

The prompt/response hooks write to .cursor/events/before-submit-prompt.csv and after-agent-response.csv. If those files stay empty (headers only):

1. Confirm Cursor is using project hooks
   Cursor reads .cursor/hooks.json from the workspace root. If you opened a parent folder or a different root, that folder’s hooks.json is used (or none). Open the repo that contains .cursor/hooks.json as the workspace root.

2. Run the hook by hand (from the repo root):

   echo "{\"conversation_id\":\"test\",\"generation_id\":\"test\"}" | node .cursor/hooks/log-before-submit-prompt.js

   Then check .cursor/events/before-submit-prompt.csv for a new row. If you see it, the script and path are fine; Cursor may not be invoking the hook (e.g. hook support or config location).

3. Check Cursor’s output
   If the hook runs but gets bad input (e.g. encoding on Windows), you may see [log-before-submit-prompt] Invalid JSON: in the terminal or Cursor’s developer tools.

Configuration

You can also provide parameters via environment variables instead of command-line arguments:

• CURSOR_HISTORY_PROJECT_CODE – project code
• CURSOR_HISTORY_INSTALLATION_TOKEN – installation token
• CURSOR_HISTORY_UPLOAD_URL – full cursor-history endpoint URL

Note: The installation token is validated during installation and must be valid and not expired. Tokens expire 24 hours after generation.

Publishing

Publishing is done by the GitHub workflow Publish Stella Cursor Installer (push to production, tag stella-cursor-install-v*, or manual dispatch). It requires the NPM_TOKEN secret.

If publish fails with 404 Not Found for @hatchworksai/stella-cursor-install:

1. Create the npm organization hatchworksai at npmjs.com/org/create if it does not exist.
2. Add the npm user whose token is in NPM_TOKEN to that org with a role that can publish (e.g. Developer).
3. Use a token that can publish (e.g. Automation token or Classic token with "Publish packages").

License

MIT