SpecStory
Docs›Quickstart

Getting Started

Quickstart

Install SpecStory and capture your first AI conversation in minutes.

SpecStory works across multiple tools. Follow the steps to setup SpecStory for your editor or workflow and get started quickly.

Cursor

Install from Cursor's marketplace and verify autosave to .specstory/history/.

VS Code + Copilot

Install the VSIX from VS Code and confirm conversations are saved locally.

Terminal Agents

Run Claude Code, Cursor CLI, Codex CLI, or Gemini CLI through SpecStory.

Cursor

Install

  1. Open Cursor.
  2. Extensions (Ctrl/Cmd+Shift+X) → search SpecStory → Install.
  3. Verify via Command Palette (Ctrl/Cmd+Shift+P) → type SpecStory.

Warning

Installing from the Visual Studio Marketplace website can leave VS Code installed but not Cursor. Install inside Cursor.

Verify autosave

  1. Chat with Cursor’s AI in a workspace folder.
  2. Check <your-project>/.specstory/history/ for a Markdown file representing your session.

👉 Learn more in Integrations → VS Code + Copilot.

VS Code (Copilot)

Install

  1. Open VS Code with GitHub Copilot enabled.
  2. Extensions (Ctrl/Cmd+Shift+X) → search SpecStory → Install.
  3. Verify via Command Palette (Ctrl/Cmd+Shift+P): type SpecStory.

Verify autosave

  1. Start a Copilot chat in your workspace.
  2. Check <your-project>/.specstory/history/ for a new Markdown file.

👉 More details in Integrations → VS Code + Copilot.

Terminal Coding Agents

Wrap your terminal-based AI assistant with SpecStory to capture a Markdown history of the entire chat and tool output.

Install the SpecStory CLI, then run Claude through the wrapper:

brew tap specstoryai/tap
brew update
brew install specstory
specstory run claude
specstory sync claude

Dive deeper →

Capture Cursor CLI sessions and retroactively export past chats:

brew tap specstoryai/tap
brew update
brew install specstory
specstory run cursor
specstory sync cursor

Dive deeper →

Launch Codex CLI via SpecStory to archive GPT-driven workflows:

brew tap specstoryai/tap
brew update
brew install specstory
specstory run codex
specstory sync codex

Dive deeper →

Launch Gemini CLI via SpecStory to archive Gemini-driven workflows:

brew tap specstoryai/tap
brew update
brew install specstory
specstory run gemini
specstory sync gemini

Dive deeper →

Generated files appear in <your-project>/.specstory/history/.

Tip

Linux/WSL: download binaries from the GitHub releases page. Each guide covers platform-specific paths and tips.

👉 Explore the full overview in Integrations → Terminal Coding Agents or open the dedicated guides for Claude Code, Cursor CLI, Codex CLI, and Gemini CLI.

Troubleshooting quick checks

  • No files in .specstory/history/: Confirm you are inside a project folder with write permissions.
  • Cursor VS Code not saving: Ensure the extension is installed in the correct editor (Cursor vs VS Code) and restart the editor.
  • CLI not capturing: Run specstory check and confirm the terminal agent runs from your shell (e.g., claude --version).
  • Still stuck? See Integrations for storage paths and known issues, or contact support@specstory.com.

Next steps