entireio-cloud-agent

# Entire Cloud-Agent Capture Setup Wire a repository so a supported agent running in a fresh cloud/headless VM is captured by [Entire](https://entire.io) and linked to Git history as a checkpoint without manual setup each session. Claude Code on the web and Cursor Cloud Agent have separate recipes because their lifecycle and transcript behavior differs. This skill captures agent work into Git. Rendering or consuming Entire data in an application is product work and is out of scope. ## How capture works A fresh VM needs three things: 1. The `entire` CLI and `git-remote-entire` helper. 2. Committed agent lifecycle hooks, such as `.claude/settings.json` or `.cursor/hooks.json`. 3. Git hooks that stamp `Entire-Checkpoint` and maintain `entire/checkpoints/v1`. Git hooks live outside version control, so setup must re-arm them on every fresh VM with `entire configure`. Capture modes: - **Local Git capture** needs no login and stores checkpoints on the local `entire/checkpoints/v1` ref. - **Platform sync** uses `ENTIRE_TOKEN`, supplied only as an environment secret. Obtain it with `entire auth token` on a logged-in machine. Normal commit/push activity then synchronizes checkpoint data. ## When to use Use this skill for remote or ephemeral coding-agent environments. For an agent running locally on the user's persistent machine, `entire enable` once is usually sufficient; confirm before installing cloud bootstrap machinery. Do not use this skill for application UI integrations, screenshot/video capture, or unrelated MCP configuration. ## Templates and recipes Shared deliverables: | Piece | Template | Destination | |-------|----------|-------------| | Session setup | `templates/setup-entire.sh` | `scripts/setup-entire.sh` | | Repo enablement | `templates/entire-settings.json` | `.entire/settings.json` | | Local scratch ignores | `templates/entire-gitignore` | `.entire/.gitignore` | Agent-specific deliverables: | Piece | Template | Destination | |-------|----------|-------------| | Claude Code hooks | `templates/claude-code-settings.json` | merge into `.claude/settings.json` | | Cursor environment install | `templates/cursor-environment.json` | merge/create `.cursor/environment.json` | | Cursor lifecycle hooks | `templates/cursor-hooks.json` | merge/create `.cursor/hooks.json` | | Cursor Cloud coordinator | `templates/entire-cloud-bootstrap.sh` | `.cursor/hooks/entire-cloud-bootstrap.sh` | | Cursor transcript shim | `templates/entire-transcript-shim.py` | `.cursor/hooks/entire-transcript-shim.py` | | Cursor environment installer | `templates/cursor-cloud-install.sh` | `scripts/cursor-cloud-install.sh` | | Agent | Recipe | |-------|--------| | Claude Code | `recipes/claude-code.md` | | Cursor Cloud Agent | `recipes/cursor-cloud.md` | Make a todo list and work through the workflow. ## Workflow ### 1. Detect the environment and agent - `.claude/` or explicit Claude Code usage selects the Claude recipe. - `.cursor/`, `CURSOR_AGENT=1`, a `bc-*` Cursor conversation ID, or explicit Cursor Cloud usage selects the Cursor recipe. - If both configs exist, determine which agent owns capture and apply the dual-agent guard described by the Cursor recipe. - Verify `git rev-parse --git-dir` succeeds. Entire capture is Git-anchored. - Confirm this is remote/ephemeral rather than a persistent local IDE. ### 2. Confirm scope Pin down: - Local-only capture or platform sync. Default to local-only and mention `ENTIRE_TOKEN` as an optional secret. - Which agent or agents to enable. - Whether to commit the generated files. Default to creating them for review and ask before committing unless the user already requested a commit. ### 3. Add shared repo configuration Copy: - `templates/entire-settings.json` to `.entire/settings.json`. - `templates/entire-gitignore` to `.entire/.gitignore`. - `templates/setup-entire.sh` to `scripts/setup-entire.sh`, then make it executable. Merge rather than replace existing project files. Confirm the top-level `.gitignore` does not exclude `.entire/`. The nested Entire gitignore keeps logs, metadata, redactors, temporary state, and local settings untracked. `absolute_git_hook_path: true` is deliberate: cloud tool shells may not inherit PATH, so installed Git hooks must call the CLI by full path. ### 4. Wire the selected agent Follow the matching recipe exactly. For **Claude Code**, merge `templates/claude-code-settings.json` into the existing settings. Setup must precede Entire's `session-start` hook in `SessionStart`. Lifecycle commands fail open if the CLI is unavailable. For **Cursor Cloud**, install all Cursor templates listed above. Preserve the ordering and stock wrapper shape in `cursor-hooks.json`. Cursor Cloud does not fire a usable initial `sessionStart`, so `.cursor/environment.json` must run the environment installer before turn one. The bootstrap then waits for a readiness sentinel, denies the first tool if capture is not armed, synthesizes the missing lifecycle, and supplies the transcript Cursor Cloud may not flush. ### 5. Understand the shared setup script `templates/setup-entire.sh` is idempotent and deliberately never fails an agent session. It: 1. Installs `entire` and `git-remote-entire` with `go install` if missing. 2. Adds `~/.local/bin` to current and future shell PATHs. 3. Runs `entire configure --force --absolute-git-hook-path` when committed Entire settings exist, or first-time `entire enable --agent "$ENTIRE_AGENT"` otherwise. 4. Reports whether `ENTIRE_TOKEN` enables platform sync. Set `ENTIRE_AGENT=claude-code` or `ENTIRE_AGENT=cursor` as appropriate. The Cursor environment installer does this automatically. ### 6. Validate the actual installation Always lint generated artifacts and exercise setup from the target repository. At minimum: ```bash bash -n scripts/setup-entire.sh python3 -m json.tool .entire/settings.json >/dev/null ENTIRE_AGENT=<agent> bash scripts/setup-entire.sh export PATH="$HOME/.local/bin:$PATH" command -v entire entire version entire status entire agent list test -f "$(git rev-parse --git-path hooks/commit-msg)" ``` Also run the recipe-specific validation. For Cursor this includes syntax checks for both helpers and JSON configs, running `scripts/cursor-cloud-install.sh`, and checking `.entire/logs/cursor-hooks.log` from a fresh cloud run. The strongest proof is a throwaway commit on a scratch branch followed by a check for an `Entire-Checkpoint` trailer and an advanced `entire/checkpoints/v1` ref. Clean up the scratch commit afterward. Do not make this commit unless the user has authorized repository history changes. ### 7. Commit and push when requested Stage only the intended config, hooks, and scripts. Never commit `ENTIRE_TOKEN` or files ignored by `.entire/.gitignore`. Do not commit directly to a protected default branch unless explicitly requested. ## Gotchas - **Use `go install` on restricted proxies.** Release-asset downloads may be blocked in hosted agents while the Go module proxy remains available. If Go is unavailable, shared setup logs and skips capture for that session. - **Git hooks are not version-controlled.** They must be reinstalled on every fresh VM. Agent config is committed; `.git/hooks` is not. - **Claude `SessionStart` ordering is load-bearing.** Setup must run before Entire's Claude `session-start` hook. - **Cursor Cloud requires its own recipe.** It does not reliably fire `sessionStart`, expose the first user prompt, or flush a native transcript. Do not treat it as a Claude Code environment. - **Cursor readiness fails closed only for cloud tools.** The environment install must produce the sentinel after both the CLI and Git hook are ready. Local Cursor IDE sessions bypass the cloud shim. - **Preserve Cursor's stock wrapper prefix.** Moving PATH export ahead of the initial `command -v entire` check can make `entire agent list` report that hooks are not installed even when they execute. - **Python is required for Cursor Cloud.** The shim uses `fcntl`, so this path is intended for Cursor's Linux runner, not native Windows. - **Transcript redaction is bounded, not infallible.** Prompts, responses, and sanitized tool data are persisted. Never place secrets in agent content. - **The first Cursor prompt is unavailable.** Capture starts at the first agent message/tool event; subsequent prompts are captured. - **Platform sync requires a real secret.** Never commit `ENTIRE_TOKEN`. - **Avoid broad process killing.** `pkill -f entire` can match the agent's own command line in shared environments; target specific PIDs instead. ## Out of scope - Rendering checkpoints in an application's UI. - Screenshot or video capture. - Generic MCP setup unrelated to Entire capture.