Cursor - Entire

Cursor Documentation

Cursor is an AI-powered code editor available as both an IDE and a command-line agent. Entire integrates with Cursor through its hook system, capturing sessions and checkpoints across both interfaces. The Cursor integration is in preview and may contain bugs.

Prerequisites

• Entire CLI installed
• Cursor IDE or Cursor CLI installed
• A Git repository with Entire enabled

Enable

entire agent add cursor
cursor   # or: agent  (for Cursor CLI)

Rewind and resume are not available for Cursor sessions. You can use other Entire commands (status, doctor, checkpoint explain, disable), but cannot restore to previous checkpoints. Plan your commits carefully — you cannot undo changes via entire checkpoint rewind.

How it works

Entire integrates with Cursor through hook configuration in .cursor/hooks.json. Both Cursor IDE and Cursor CLI are supported — choose the IDE for traditional development workflows or the CLI for scripted tasks, parallel processing, or terminal-first development. The hooks track the full session lifecycle:

1. Session Start — fires when Cursor launches, creating a new Entire session.
2. Prompt Tracking — before-submit-prompt hook captures each prompt submission.
3. Subagent Tracking — subagent-start and subagent-stop hooks track nested agent operations.
4. Session End — fires when Cursor exits, finalizing the session.
5. Compaction — pre-compact hook triggers before session data compaction.
6. Transcript Capture — session transcript is read from Cursor’s JSONL log files.
7. Session Storage — data saved to the entire/checkpoints/v1 branch.

What gets captured

Unlike Claude Code, Cursor transcripts do not include token usage data or detailed tool invocation records.

Features

Session capture. Entire automatically captures the conversation flow and file modifications when Cursor launches. Run entire status from a separate terminal to see active sessions.

Explain commits. Inspect any commit or checkpoint with entire checkpoint explain. See the checkpoint explain command reference for full flag documentation. Rewind and resume are not supported.

Caveats and limitations

No rewind or resume. Cannot restore to previous checkpoints; cannot resume previous sessions.

No token accounting. Cursor transcripts do not include token usage data (unlike Claude Code). You can still see the conversation and file changes, but not the computational cost.

File detection via git status. Cursor’s transcript format lacks detailed tool invocation records, so modified file detection relies on git status instead of transcript analysis. This means files must be committed or staged to be tracked, and the file change detection is accurate but less granular than Claude Code.

Context attachment differences (CLI). When using Cursor CLI, the @ syntax for attaching files/folders as context does not behave identically to the IDE. The IDE’s @ mentions work through the AI chat interface for context selection; the CLI may require different handling — check Cursor CLI documentation for current behavior.

No detailed tool records. Tool invocation details are limited compared to Claude Code.

Preview integration. May contain rough edges or undocumented behavior.

Best practices

Commit at logical points. Create checkpoints at natural stopping points: after implementing a feature, before making major changes, or when you’d want to document progress. Especially important since rewind is not available.

Review sessions in PRs. Commits include Entire-Checkpoint trailers. Reviewers can click through to view session details — understanding why code was written helps with review.

Example workflow

With Cursor IDE:

# 1. Enable Entire
cd my-project
entire agent add cursor

# 2. Start Cursor IDE
cursor

# 3. Work with Cursor IDE
# Use @ mentions to attach files for context
# Ask the AI to implement features

# 4. Check status (in another terminal)
entire status

# 5. Commit when ready
git add .
git commit -m "Add feature with Cursor"

# 6. Push to see on entire.io
git push

With Cursor CLI:

# 1. Enable Entire
cd my-project
entire agent add cursor

# 2. Run Cursor CLI
agent

# 2.1 Instruct Cursor CLI
"refactor the authentication module"

# 3. In parallel terminal, run another Cursor CLI
agent

# 3.1 Instruct the other CLI
"update database schema"

# 4. Check both sessions
entire status

# 5. Commit all changes
git add .
git commit -m "Parallel refactoring with Cursor CLI"

# 6. Push to see on entire.io
git push

Troubleshooting

Session not being captured

1. Verify Entire is enabled: entire status
2. Check that hooks are installed: cat .cursor/hooks.json
3. Ensure Cursor is running from within the repository
4. For Cursor CLI, verify the process exits cleanly to trigger session-end hook

No checkpoints created

1. Checkpoints require file changes — ensure Cursor is modifying files
2. Changes must be staged or committed (git status is used for detection)
3. Check your settings in .entire/settings.json
4. Verify the .cursor/hooks.json hooks are present

Transcript not captured

1. Ensure Cursor’s session storage exists (check ~/.cursor/ directory)
2. Verify JSONL transcript files are being written by Cursor
3. Check that the session completed normally (session-end hook must fire)
4. Look for errors in Entire hook output with entire doctor

File changes not showing in transcript

This is expected behavior for Cursor. Since transcripts lack tool_use blocks, file detection relies on git status. Make sure to:

1. Stage or commit your changes with git add and git commit
2. Run entire status to verify files are detected
3. Review actual file changes in git diff if transcript shows nothing

Context not attached (CLI)

When using Cursor CLI, @ mentions for file context may not work identically to the IDE:

1. Check Cursor CLI documentation for current context attachment syntax
2. Consider using environment variables or configuration files for context
3. Include relevant files in your initial prompt text instead of @ mentions