Skip to main content
SpecStory Cloud helps you move from individual capture to shared, searchable context across your team. This guide walks you through creating an account, syncing your first project, and running your first search.

​
1. Create your SpecStory Cloud account

  • Go to cloud.specstory.com.
  • Sign up with your email or GitHub account.
  • Verify your email and log in.
  • One logged in, you’ll land on an empty dashboard until you sync a project.
Once logged in, you’ll see the Cloud Dashboard. It will be empty at first until you sync your histories and project.
SpecStory is local‑first. Nothing is synced until you explicitly turn on sync on your machine.

​
2. Ensure local capture is working

SpecStory Cloud builds on top of the local .specstory/history/ your tools already write. Choose your setup and confirm you see Markdown files locally before enabling sync.

​
Cursor / VS Code with GitHub Copilot

Install the SpecStory extension from the marketplace.
  1. Open Cursor or VS Code.
  2. Search for SpecStory in the Extensions Marketplace (Ctrl/Cmd+Shift+X).
  3. Click Install.
  4. Restart your editor.
For detailed installation instructions, see our Installation Guide. Once installed, open any project folder, start an AI chat, and confirm that .specstory/history/ appears in your repo with Markdown files.

​
Claude Code / Cursor CLI / Codex CLI

Install the SpecStory CLI and capture terminal agent sessions locally. macOS (via Homebrew): 
brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check
specstory run claude # launches Claude Code and captures the session
specstory run cursor # launches Cursor CLI and captures the session
specstory run codex # launches Codex CLI and captures the session
specstory sync # converts existing sessions to Markdown
Linux/WSL: Download the latest release from our GitHub releases and follow the Linux installation instructions in our Installation Guide. Run Claude Code through SpecStory: 
specstory version
specstory check
specstory run claude # launches Claude Code and captures the session
specstory run cursor # launches Cursor CLI and captures the session
specstory run codex # launches Cursor CLI and captures the session
specstory sync # converts existing sessions to Markdown

​
BearClaude (macOS)

Use BearClaude to author specs and talk to Claude Code. It saves your sessions to .specstory/history/ in the project you open.
If .specstory/history/ isn’t present, complete a short AI conversation first. The first Markdown file is created on save/auto-save.

​
3. Authenticate your device for Cloud

Run once per machine to allow uploads from the CLI/extension: 
specstory login
This opens a browser window to complete a secure login. Your device stores a token locally and future syncs use it automatically.
Authentication enables sync, but does not upload anything by itself.

​
4. Sync your first project

You control what (and when) to sync. Pick the path that matches your setup.

​
A) From Cursor / VS Code extensions

  1. Open the project folder that is already using SpecStory and also contains .specstory/history/.
  2. Open the Command Palette (Ctrl/Cmd+Shift+P) and run SpecStory: Open Cloud Sync Configuration.
  3. This will open a configuration screen where you can:
    • Ensure you’re logged in
    • Enable sync for this project
    • Optionally enable sync for all future projects
  4. Once configured, your sessions will sync automatically. Visit the Cloud dashboard to verify sessions appear.

​
B) From the CLI

# Sync all local sessions in the current repo/project
specstory sync

# Sync a single session by ID
specstory sync claude -s <session-uuid>
After sync, refresh cloud.specstory.com, you should see the project and synced sessions.
  1. Open cloud.specstory.com and use the search bar.
  2. Use the search bar to query across your synced histories.
  3. Apply filters:
    • Projects (multi‑select)
    • Time Range
  4. Open a result to review the results.
Search combines keyword and semantic retrieval so you can quickly resurface reasoning, tradeoffs, or design threads.
Search runs across all projects you’ve synced, so it’s ideal for cross‑repo discovery.

​
6. Current scope of collaboration

SpecStory Cloud currently supports single‑user. Each developer can sync their own histories and search them centrally. Team workspaces, invitations, and role‑based access are on the roadmap. What you can do today:
  • Each teammate can sync their own .specstory/history/ to Git for code‑adjacent review in PRs and docs.
  • Sessions can be exported or shared manually if needed.

​
Best practices

  • Start small with one repo: Sync one project first and validate capture → sync → search before rolling out to all repos.
  • Be intentional about what you sync: Version your .specstory/history/ in Git and use Cloud for team-wide search.
  • Tag important sessions: Improves later search and retrieval.

​
Troubleshooting

  • No sessions appear after sync
    • Confirm .specstory/history/ exists and contains Markdown files.
    • Run specstory login again if your token expired.
    • Re‑run specstory sync from the project root.
  • Command Palette action missing (Cursor/VS Code)
    • Verify the SpecStory extension is installed and enabled in that editor.
    • Restart the editor after installation.
  • CLI can’t find Claude Code sessions
    • Ensure you launched Claude Code via specstory run so the wrapper can capture sessions.
    • Use specstory sync to convert existing session logs to Markdown.
Need help? Open an issue at github.com/specstoryai/getspecstory or email support@specstory.com.

​
Where to next

Sync & Store

Configure sync from extensions and CLI; verify uploads.

Search & Organization

Master filters and result exploration.
⌘I