[luv-245] feat: add Cursor Agent CLI integration (beta)

[NiveditJain]

Summary

• Adds Cursor Agent CLI as a 4th supported agent CLI alongside Claude Code, OpenAI Codex, and GitHub Copilot — full feature parity (hooks install/uninstall, dashboard activity feed, /projects merge, session viewer fallback chain). Bumps version to 0.0.10-beta.1.
• Cursor's hook protocol differs from the others on several axes; the integration handles each:
  • camelCase event keys (preToolUse, beforeSubmitPrompt, …) — handler.ts canonicalizes via CURSOR_EVENT_MAP so existing builtin policies fire unchanged.
  • Flat array per event (no Claude-style {hooks: [...]} matcher wrapper) — writeHookEntries / removeHooksFromFile / hooksInstalledInSettings walk the flat structure.
  • Different stdout shape ({permission, user_message, agent_message, additional_context, followup_message}) — policy-evaluator.ts branches on session.cli === "cursor" for deny / instruct / allow-with-info.
  • No documented permission-mode equivalent — falls into the existing default branch.
  • Detected via cursor-agent (preferred) or agent (legacy alias).
• Settings paths: ~/.cursor/hooks.json (user) / <cwd>/.cursor/hooks.json (project).
• Path-protection (isAgentInternalPath + isAgentSettingsFile) extended to cover ~/.cursor/ and .cursor/hooks.json.
• Frontend: lib/cli-registry.ts adds a Cursor Agent entry with an emerald badge; lib/projects.ts merges Cursor projects; the project page and session viewer extend the external-CLI fallback chain. Activity feed recognizes /.cursor/ transcript paths.
• Adds lib/cursor-projects.ts + lib/cursor-sessions.ts as scaffold parsers — Cursor's transcript layout is undocumented, so the modules probe candidate subdirs (agent-sessions/, conversations/, sessions/) and metadata files (meta.json / session.json / workspace.{json,yaml}) and gracefully return [] when the layout doesn't match. Once the user reports the real layout the parser is one constant change away from a precise match.
• Drops .cursor/hooks.json at the project root so contributors using Cursor get hooks active automatically (mirrors the existing .codex/hooks.json and .github/hooks/failproofai.json). .gitignore adjusted to track that single file.
• Adds light/dark Cursor logo SVGs in assets/logos/ and the visual <picture> block in README.md.
• Pre-existing parity fix: app/project/[name]/page.tsx previously listed only Claude + Codex sessions, missing Copilot (and now Cursor); it now merges all four sources.

Test plan

• bun run lint — clean (1 unrelated <img> warning)
• bun run test:run — 60 suites / 1228 tests pass (including new __tests__/lib/cursor-sessions.test.ts, __tests__/lib/cursor-projects.test.ts, extended cli-registry.test.ts, projects.test.ts, project-list.test.tsx, integrations.test.ts, install-prompt.test.ts, handler.test.ts)
• bun run build — Next.js + dist/index.js build succeeds; type-check passes
• bun run test:e2e — 9 suites / 235 tests pass (including the new __tests__/e2e/hooks/cursor-integration.e2e.test.ts)
• Local smoke test — failproofai policies --install --cli cursor --scope project writes .cursor/hooks.json with 6 camelCase entries; --uninstall cleans it
• Docker clean-install test — to follow up if CI needs it; the e2e binary path test already covers the install flow

Open follow-ups

• Cursor's on-disk transcript format isn't documented. The scaffold parsers + path probes return [] gracefully; once we observe a real install, swap the candidate constants in lib/cursor-{sessions,projects}.ts for precise matches.
• i18n READMEs (docs/i18n/README.*.md) and docs/zh/, docs/pt-br/ translations will pick up the Cursor mentions on the next bun run translate cycle (same pattern as [luv-236] feat: add GitHub Copilot CLI integration (beta) #236 / [auto] update translations #233).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for Cursor Agent CLI integration (beta)
  • Dashboard now discovers and displays Cursor Agent sessions
  • Policy installation works with Cursor Agent via --cli cursor flag
  • Session viewer displays Cursor Agent activity logs
  • Activity dashboard includes Cursor Agent event filtering

[coderabbitai]

Warning

Rate limit exceeded

@NiveditJain has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 47 minutes and 51 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: eaf8bb14-9ee0-4a69-8252-6e0867b6a340

📥 Commits

Reviewing files that changed from the base of the PR and between b4c1f64 and 69da6f6.

📒 Files selected for processing (4)

• .cursor/hooks.json
• CHANGELOG.md
• lib/cursor-projects.ts
• lib/cursor-sessions.ts

📝 Walkthrough

Walkthrough

Adds Cursor Agent CLI integration across the failproofai hook system, project/session discovery, policy evaluation, and dashboard. Includes new Cursor-specific modules for session/project scanning, hook configuration support, event-name canonicalization, decision output formatting, registry entries, comprehensive test coverage, and documentation updates.

Changes

Cohort / File(s)	Summary
Configuration & Gitignore .cursor/hooks.json, .gitignore	Introduces Cursor hook configuration file and updates ignore patterns to track it while excluding other .cursor/ contents.
Documentation README.md, CLAUDE.md, CHANGELOG.md, docs/*	Advertises Cursor Agent (beta) as supported CLI, documents hook installation/event-mapping for Cursor, updates dashboard discovery/viewer descriptions, and logs changelog entries.
CLI & Hook System Core bin/failproofai.mjs, src/hooks/handler.ts, src/hooks/install-prompt.ts, src/hooks/resolve-permission-mode.ts, src/hooks/builtin-policies.ts	Extends CLI argument validation and help text to accept --cli cursor, adds Cursor-specific event-name canonicalization from camelCase to PascalCase, updates builtin policy matchers to guard .cursor/hooks.json, and adjusts permission-mode fallback comments.
Hook Integration & Types src/hooks/types.ts, src/hooks/integrations.ts	Defines Cursor-specific constants (CURSOR_HOOK_EVENT_TYPES, CURSOR_HOOK_SCOPES, CURSOR_EVENT_MAP) and implements new cursor integration adapter that reads/writes .cursor/hooks.json, manages hook lifecycle, and ensures camelCase event keys.
Policy Evaluation src/hooks/policy-evaluator.ts	Adds Cursor-specific stdout formatting: flat {permission, user_message, agent_message} on deny, {followup_message} or {permission, additional_context} on instruct/allow, replacing previous event-specific wrappers.
CLI Registry lib/cli-registry.ts	Adds "cursor" to KNOWN_CLI_IDS type and CLI_ENTRIES metadata with label and emerald badge CSS classes.
Project & Session Discovery lib/cursor-projects.ts, lib/cursor-sessions.ts, lib/projects.ts	Introduces new Cursor session/project discovery modules that scan ~/.cursor/agent-sessions/ (respecting CURSOR_HOME), parse Cursor JSONL event logs with cwd extraction and tool correlation, and integrate discovered projects into the main project-folder merging pipeline.
Dashboard & Session Viewers app/policies/hooks-client.tsx, app/project/[name]/page.tsx, app/project/[name]/session/[sessionId]/page.tsx	Extends SessionCell to detect and link Cursor sessions, updates project detail page to query external Cursor sessions in parallel, and adds Cursor session log loading and UI rendering to the session viewer.
Hook System Tests __tests__/hooks/handler.test.ts, __tests__/hooks/install-prompt.test.ts, __tests__/hooks/integrations.test.ts	Adds test coverage for Cursor event-name normalization, telemetry tracking, integration lifecycle (install/uninstall/detection), hook entry construction, and event-map completeness.
Library Tests __tests__/lib/cursor-projects.test.ts, __tests__/lib/cursor-sessions.test.ts, __tests__/lib/projects.test.ts, __tests__/lib/cli-registry.test.ts	Introduces comprehensive test suites for Cursor project/session discovery with metadata scanning fallbacks, JSONL parsing with tool correlation, project merging, and CLI registry Cursor entry validation.
E2E & Component Tests __tests__/e2e/hooks/cursor-integration.e2e.test.ts, __tests__/e2e/helpers/hook-runner.ts, __tests__/e2e/helpers/payloads.ts, __tests__/components/project-list.test.tsx	Adds end-to-end hook runner tests verifying deny/instruct/allow paths, activity logging, and install/uninstall behavior; introduces Cursor payload factories and assertion helpers; extends project-list component tests to verify Cursor badge rendering and CLI filter options.
Package Metadata package.json	Increments version from 0.0.10-beta.0 to 0.0.10-beta.1.

Sequence Diagram

sequenceDiagram
    participant CursorCLI as Cursor CLI
    participant Hook as Hook Runner
    participant Handler as Event Handler
    participant Evaluator as Policy Evaluator
    participant Output as Decision Output

    CursorCLI->>Hook: Invokes hook with camelCase event<br/>(preToolUse, postToolUse, etc.)
    Hook->>Handler: Passes stdin payload to failproofai
    Handler->>Handler: Canonicalizes camelCase to PascalCase<br/>(preToolUse → PreToolUse)
    Handler->>Evaluator: Evaluates policy against<br/>canonical event type
    Evaluator->>Evaluator: Determines decision<br/>(deny/instruct/allow)
    alt Deny Decision
        Evaluator->>Output: Build blocked message
        Output->>CursorCLI: Return flat Cursor format<br/>{permission: "deny",<br/>user_message, agent_message}
    else Instruct Decision
        Evaluator->>Output: Build followup/context message
        Output->>CursorCLI: Return Cursor format<br/>{followup_message} or<br/>{permission: "allow",<br/>additional_context}
    else Allow Decision
        Evaluator->>Output: Build allow response
        Output->>CursorCLI: Return {permission: "allow",<br/>additional_context}
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• [luv-236] feat: add GitHub Copilot CLI integration (beta) #236: Parallel Copilot Agent CLI integration adopting the same multi-module pattern (integrations.ts, types.ts, handler.ts, policy-evaluator.ts, project/session discovery).
• [hooks] add OpenAI Codex hook integration alongside Claude Code #220: Codex CLI integration adding the same structural changes—integration adapter, event canonicalization, CLI registry entry, and policy-evaluator output formatting.
• chore: add .failproofai config directory #94: Hook policy evaluation and telemetry changes (instruct-result accumulation, decision tracking) affecting the same policy-evaluator.ts control flow.

Poem

🐰 Hop, hop, the Cursor comes to play,
Events camelCase'd, then cast to Pascal's way,
Projects and sessions cached in burrows deep,
Hook events evaluated—promises we keep! ✨🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.66% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[luv-245] feat: add Cursor Agent CLI integration (beta)' directly and clearly summarizes the primary change: adding Cursor Agent CLI support as a new integration alongside existing agent CLIs.
Description check	✅ Passed	The PR description comprehensively covers the work: Summary section explains what was added and why, detailed subsections describe protocol differences, settings paths, frontend changes, and new modules, Test plan documents all test suites with pass counts, and Open follow-ups clarify future refinements. All required template sections (Description, Type of Change, Checklist) are addressed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch luv-245

Warning

Review ran into problems

🔥 Problems

Timed out fetching pipeline failures after 30000ms

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 47 minutes and 51 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.cursor/hooks.json:
- Line 9: Remove the non-schema field "__failproofai_hook__" from all hook
objects in .cursor/hooks.json; Cursor only allows "type", "command", and
"timeout" per hook, so locate each hook entry containing the
"__failproofai_hook__" property and delete that key/value pair (preserving the
allowed fields like "type", "command", and "timeout") so the file conforms to
the hooks.json schema.

In `@CHANGELOG.md`:
- Around line 12-17: The changelog added a second "### Features" block under "##
Unreleased"; instead, merge the new Cursor Agent and Project page bullets into
the existing Unreleased subsections (fold the Cursor Agent CLI integration
details and the Project page bullet into the existing "### Features" and fold
README/logo note into "### Docs"), remove the duplicate "### Features" heading,
and keep references to the implemented symbols (CURSOR_EVENT_MAP,
isAgentInternalPath, isAgentSettingsFile, lib/cli-registry.ts, lib/projects.ts,
app/project/[name], /session/[id], and assets/logos/cursor-light.svg +
cursor-dark.svg) in-line within the appropriate subsection so the Unreleased
block remains a single coherent set of subsections.

In `@lib/cursor-projects.ts`:
- Around line 71-78: The JSON branch in parseCwdFromMetaText returns the raw
escaped string; instead try to JSON.parse the input text (inside a try/catch)
and read the cwd property so escape sequences (e.g. Windows backslashes) are
decoded, returning parsed.cwd if present; if JSON.parse throws or cwd is
missing, fall back to the existing regex checks (the YAML regex and the current
string-unquote step) so behavior remains unchanged for non-JSON metadata.

In `@lib/cursor-sessions.ts`:
- Around line 165-200: The user/assistant message branches in
lib/cursor-sessions.ts currently cast data.content/data.text with "as string"
and may push non-string values; update the user.message and assistant.message
handling (the lines that set `text = (data.content as string) ?? (data.text as
string) ?? ""` and the assistant ContentBlock creation) to first check typeof
data.content === "string" or typeof data.text === "string" and only use those
values when true, otherwise fall back to "" (and keep existing fallback to
pushing a GenericEntry when no text); ensure the produced entries (UserEntry,
AssistantEntry) always have string message content/ContentBlock.text to avoid
passing objects to the renderer while keeping baseEntry and rawCopy usage
intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de718b89-4db5-4f7a-b48d-d35b627cb013

📥 Commits

Reviewing files that changed from the base of the PR and between 6c259fc and b4c1f64.

⛔ Files ignored due to path filters (2)

• assets/logos/cursor-dark.svg is excluded by !**/*.svg
• assets/logos/cursor-light.svg is excluded by !**/*.svg

📒 Files selected for processing (35)

• .cursor/hooks.json
• .gitignore
• CHANGELOG.md
• CLAUDE.md
• README.md
• __tests__/components/project-list.test.tsx
• __tests__/e2e/helpers/hook-runner.ts
• __tests__/e2e/helpers/payloads.ts
• __tests__/e2e/hooks/cursor-integration.e2e.test.ts
• __tests__/hooks/handler.test.ts
• __tests__/hooks/install-prompt.test.ts
• __tests__/hooks/integrations.test.ts
• __tests__/lib/cli-registry.test.ts
• __tests__/lib/cursor-projects.test.ts
• __tests__/lib/cursor-sessions.test.ts
• __tests__/lib/projects.test.ts
• app/policies/hooks-client.tsx
• app/project/[name]/page.tsx
• app/project/[name]/session/[sessionId]/page.tsx
• bin/failproofai.mjs
• docs/configuration.mdx
• docs/dashboard.mdx
• docs/getting-started.mdx
• lib/cli-registry.ts
• lib/cursor-projects.ts
• lib/cursor-sessions.ts
• lib/projects.ts
• package.json
• src/hooks/builtin-policies.ts
• src/hooks/handler.ts
• src/hooks/install-prompt.ts
• src/hooks/integrations.ts
• src/hooks/policy-evaluator.ts
• src/hooks/resolve-permission-mode.ts
• src/hooks/types.ts