Cursor

1. Install the SpecStory extension in Cursor.
2. Open your project folder and start a conversation with Cursor.
3. Open .specstory/history/ to read the saved Markdown.

Autosave is enabled by default. Run SpecStory: Save AI Chat History from the Command Palette to choose conversations manually.

Reference a saved file in the next coding agent session to bring back the prompts and decisions behind a change. You can also keep history files in Git alongside the code.

Enable Cloud sync to find sessions across projects. Use session sharing to send a teammate the context behind your work.

Cursor Cloud Agents run in Cursor's cloud. You can start them from cursor.com/agents, Slack, GitHub, Linear, the Cursor apps, or the Cloud Agents API. Cursor never writes their conversations to your machine, so SpecStory reads them from the Cursor API with your own API key and saves them to .specstory/history/ alongside your other sessions.

This needs SpecStory extension 2.4.0 or later, or SpecStory CLI 2.16.0 or later. Accounts on Cursor's Privacy Mode (Legacy) can't use the Cloud Agents API.

Connect your Cursor API key

1. Create a key at cursor.com/dashboard/api.

2. Add it to ~/.specstory/cli/config.toml:

   [providers]
   cursor_api_key = "crsr_..."
   

3. Reload the Cursor window so SpecStory picks up the key.

You can set the CURSOR_API_KEY environment variable instead, and it takes precedence over the config file. Cursor may not see variables from your shell profile if you open it from the Dock or Start menu, so the config file is the simpler choice for the extension. Don't put the key in a project's .specstory/cli/config.toml, where it can be committed.

Cloud agents are saved automatically once the key is set. To stop saving them, turn off Cursor Cloud Agent in the specstory.providers.enabled setting.

Keep full transcripts

• Matching: an agent belongs to your project when it worked on the same repository as your project's git origin, so open a clone of that repository. Agents on other repositories are skipped.
• The 24-hour window: Cursor serves a run's full transcript, including tool calls and their output, for 24 hours after it finishes. After that, only the conversation text is available. To keep the details, open the project in Cursor at least once a day, or keep specstory watch cursorcloud running.
• The local copy: SpecStory keeps what it reads in .specstory/cursorcloud/. Don't delete this folder, or a run older than 24 hours can only be rebuilt from its text. It holds unredacted transcripts, so SpecStory adds a .gitignore to keep it out of Git. To move it, set cursorcloud_mirror_dir in your config.

Use the CLI with cloud agents

The extension uses the same commands as the SpecStory CLI, which you can also run yourself from a clone of the repository:

# Confirm your key works
specstory check cursorcloud

specstory list cursorcloud
specstory sync cursorcloud
specstory watch cursorcloud

specstory run cursorcloud starts a new cloud agent on your repository's current branch, or its default branch if the current one isn't pushed. It opens the agent in your browser and keeps saving until you press Ctrl+C. Cursor's API needs a first prompt, so the agent opens with a short greeting, which is a paid run. You continue the conversation in the browser.

Resume a cloud agent session

Use specstory resume to continue a cloud agent's session in a local agent, or to continue any session with specstory resume cursorcloud. A cloud agent's own session reopens that agent. Any other session starts a new cloud agent seeded with the conversation so far, which is a new paid run, and a session over 1,000,000 characters is too large to send. See search and resume for the picker and supported handoffs.

Check that SpecStory is enabled and your project folder is writable. Confirm specstory.autoSave is on. For more detail, open the Output panel and select SpecStory. See extension settings.

If cloud agents are missing, run specstory check cursorcloud to test your API key, and confirm the project's git origin is the repository the agent worked on.