## 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](https://docs.entire.io/installation)
- [Cursor IDE or Cursor CLI installed](https://www.cursor.com/)
- 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

| Data               | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| Conversation       | Full transcript of prompts and responses                           |
| File changes       | All files modified during the session                              |
| Subagent calls     | Nested agent invocations and operations                             |
| Timestamps         | Session, message, and checkpoint timing                            |

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](https://docs.entire.io/cli-reference/checkpoint#checkpoint-explain) 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