SpecStory

https://github.com/specstoryai/getspecstory
Admin
SpecStory enhances AI development workflows by providing extensions for IDEs like Cursor, GitHub...
Tokens:6,367
Snippets:42
Trust Score:7.2
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install SpecStory IDE Extensions

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Guides users on installing the SpecStory extension for Cursor IDE and VS Code with GitHub Copilot. Installation is performed directly within the IDEs. The extension is verified by checking for the creation of the `.specstory/history/` directory after the first AI interaction.

```bash
# For Cursor IDE (install from within Cursor, not VS Code Marketplace)
# 1. Open Cursor
# 2. Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux)
# 3. Search for "SpecStory"
# 4. Click Install
# Minimum version: Cursor v0.43.6+

# For VS Code with GitHub Copilot
# 1. Open VS Code
# 2. Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux)
# 3. Search for "SpecStory"
# 4. Click Install
# Minimum version: VS Code v1.300.0+

# Verify extension is active by checking for .specstory/history/
directory creation in your project after first AI interaction
```

--------------------------------

### Install SpecStory CLI using Shell Script

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Installs the SpecStory CLI directly on Linux or macOS by downloading and executing an installation script from GitHub. The script detects the platform and architecture, downloads the latest release, and sets up the executable.

```bash
# Direct installation for Linux/macOS
curl -fsSL https://raw.githubusercontent.com/specstoryai/getspecstory/main/install.sh | bash

# The script will:
# 1. Detect your platform (Darwin/Linux) and architecture (x86_64/arm64)
# 2. Download the latest release from GitHub
# 3. Install to /usr/local/bin/specstory
# 4. Set executable permissions

# Verify installation
specstory --version
# Output: SpecStory CLI v1.0.27
```

--------------------------------

### Install SpecStory CLI using Homebrew

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Installs the SpecStory Command Line Interface (CLI) using the Homebrew package manager on macOS and Linux. After installation, you can verify the version and check for detected AI agents.

```bash
# Install via Homebrew (macOS/Linux)
brew tap specstoryai/tap
brew install specstory

# Verify installation
specstory --version

# Check which AI agents are installed on your system
specstory check

# Expected output:
# ✓ Claude Code detected (v1.2.3)
# ✓ Cursor CLI detected (v2025.09.18)
# ✗ Codex CLI not found
# ✗ Gemini CLI not found
```

--------------------------------

### GOOD Change Tracking Scenario Example (Bash)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Demonstrates a scenario tracking AI and manual code changes using GOOD. It highlights how GOOD differentiates between AI-generated lines, manual edits, and their combined history, contrasting with standard Git's view.

```bash
# Example scenario tracking AI and manual changes:

# Initial state (manual creation)
# m0: create mixed-1.txt (lines 1-3)

# AI modifies existing file
# a2: modify mixed-1.txt (lines 2, 3)
# Creates shadow commit with prompt metadata

# Manual edit after AI
# m1: modify mixed-1.txt (line 3)
# GOOD tracks that line 3 was AI-generated, then manually edited

# Git commit captures both
# g0: commit mixed-1.txt
# Standard Git sees only final state

```

--------------------------------

### GOOD Git Shadow Repository Tracking Example (Bash)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Illustrates how the GOOD Git companion tracks AI-generated code changes with detailed metadata, including prompts and lineage, which is not captured by standard Git.

```bash
# Conceptual example of GOOD tracking:

# Standard Git tracks:
git log --oneline
# abc123 Implement authentication system
# def456 Add user profile page
# (Lost: which parts were AI-generated, what prompts created them)

# GOOD shadow repository tracks:
# .specstory/shadow-git/

# Each AI response creates a micro-commit with:
# - The exact lines changed
# - The prompt that generated the change
# - Relationship to manual edits
# - Linkage to standard Git commits

# Example GOOD commit message:
# [GOOD-a3] AI generated lines 1-3 of ./with-git/ai-2.txt
# Prompt: "Add authentication middleware with JWT support"
# Parent: m2 (manual commit)
# Git commit: g0

# Tracing code origin:
good origin ./with-git/mixed-2.txt:2
# Output:
# Line 2: origin=a6 (AI-generated)
# Prompt: "Add error handling for authentication failures"
# Generated: 2025-12-14T16:45:10Z
# Git commit: g1

# Finding all code from a specific prompt:
good find --prompt "authentication"
# Output:
# ./with-git/ai-2.txt:1-3 (a3)
# ./with-git/mixed-2.txt:2 (a6)
# ./auth/middleware.ts:15-30 (a9)

```

--------------------------------

### Install and Launch BearClaude CLI (Bash)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Provides commands for installing and launching the BearClaude application via its command-line interface on macOS. BearClaude is a native application for markdown editing and AI interaction.

```bash
# Install BearClaude from https://bearclaude.specstory.com

# Enable terminal command (from BearClaude → Settings)
# This installs 'bearclaude' CLI command

# Launch BearClaude from terminal
bearclaude /path/to/project
```

--------------------------------

### Get Session by ID API

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Retrieves the full details of a specific session using its unique identifier.

```APIDOC
## GET /v1/sessions/{session_id}

### Description
Fetches the complete session data, including all messages and metadata, for a given session ID.

### Method
GET

### Endpoint
/v1/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session to retrieve.

### Response
#### Success Response (200)
- (object) - The full JSON representation of the session, including messages and metadata.

#### Response Example
```json
{
  "session_id": "abc123",
  "created_at": "2025-12-16T14:30:45Z",
  "agent": "claude-code",
  "project_path": "/Users/username/myproject",
  "messages": [
    {
      "role": "user",
      "content": "Add authentication middleware",
      "timestamp": "2025-12-16T14:31:00Z"
    },
    {
      "role": "assistant",
      "content": "I'll create an authentication middleware...",
      "timestamp": "2025-12-16T14:31:15Z",
      "files_changed": ["src/middleware/auth.ts"]
    }
  ],
  "synced_to_cloud": true
}
```
```

--------------------------------

### API Authentication and Session Management (Bash)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Demonstrates how to authenticate with the SpecStory API using cURL and manage sessions. This involves logging in to obtain a token, searching for sessions with specific criteria, syncing local session data to the cloud, and retrieving session details by ID. The API uses JSON for request and response bodies.

```bash
# Authenticate
curl -X POST https://api.specstory.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secure_pass"}'
# Returns: {"token": "eyJhbGc...", "expires_at": "2025-12-17T14:30:45Z"}

# Search sessions
curl -X GET https://api.specstory.com/v1/sessions/search \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "authentication implementation", \
    "project": "myapp", \
    "date_from": "2025-12-01", \
    "date_to": "2025-12-31" \
  }'
# Returns: {"sessions": [...], "total": 15, "page": 1}

# Sync local session to cloud
curl -X POST https://api.specstory.com/v1/sessions/sync \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d @.specstory/history/2025-12-16T14-30-45-abc123.json
# Returns: {"session_id": "abc123", "synced_at": "2025-12-16T14:35:00Z"}

# Get session by ID
curl -X GET https://api.specstory.com/v1/sessions/abc123 \
  -H "Authorization: Bearer eyJhbGc..."
# Returns: Full session JSON with all messages and metadata
```

--------------------------------

### Local Project Structure and Session File Format (Bash & JSON)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Illustrates the typical directory structure for a SpecStory project, including the location of saved session history and the format of a session JSON file. It also shows how to add SpecStory's history directory to a .gitignore file to prevent version control conflicts. The session file contains metadata and conversation history.

```bash
# Typical project structure with SpecStory
myproject/
├── .specstory/
│   ├── history/                    # All saved sessions
│   │   ├── 2025-12-16T14-30-45-abc123.json
│   │   ├── 2025-12-15T09-15-22-def456.json
│   │   └── 2025-12-14T16-45-10-ghi789.json
│   └── .gitignore                 # Ignore history in git
├── src/
│   └── ... (your source code)
└── README.md

# .gitignore entry to exclude from version control:
echo ".specstory/history/" >> .gitignore
```

```json
# Session file format (simplified):
{
  "session_id": "abc123",
  "created_at": "2025-12-16T14:30:45Z",
  "agent": "claude-code",
  "project_path": "/Users/username/myproject",
  "messages": [
    {
      "role": "user",
      "content": "Add authentication middleware",
      "timestamp": "2025-12-16T14:31:00Z"
    },
    {
      "role": "assistant",
      "content": "I'll create an authentication middleware...",
      "timestamp": "2025-12-16T14:31:15Z",
      "files_changed": ["src/middleware/auth.ts"]
    }
  ],
  "synced_to_cloud": false
}
```

--------------------------------

### Launch AI Coding Assistants with SpecStory

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Launches various AI coding assistants (Claude Code, Cursor CLI, Codex CLI, Gemini CLI) through the SpecStory CLI, enabling automatic session saving. Sessions are saved locally to `.specstory/history/` as JSON files containing prompts, responses, file changes, and metadata. A default agent can also be launched.

```bash
# Launch Claude Code with automatic session saving
specstory run claude

# Launch Cursor CLI with automatic session saving
specstory run cursor

# Launch Codex CLI with automatic session saving
specstory run codex

# Launch Gemini CLI with automatic session saving
specstory run gemini

# Launch default agent (uses your configured default)
specstory run

# All sessions are automatically saved to:
# .specstory/history/<timestamp>-<session-id>.json
# Example: .specstory/history/2025-12-16T14-30-45-abc123.json

# The saved session includes:
# - All prompts and AI responses
# - File changes and diffs
# - Timestamps for each interaction
# - Metadata about the agent used
```

--------------------------------

### Search Local Sessions for Content (Bash)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Searches recursively through local session history files for a specific keyword. This is useful for quickly finding relevant information within your saved sessions.

```bash
grep -r "authentication" .specstory/history/
```

--------------------------------

### Configure Cursor IDE Extension (JSON)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Specifies settings for the SpecStory extension within the Cursor IDE. This configuration allows control over auto-sync, sync intervals, and the local storage path for session history.

```json
{
  "specstory.autoSync": true,
  "specstory.syncInterval": 300,
  "specstory.localPath": ".specstory/history/"
}
```

--------------------------------

### Access and View Local SpecStory Sessions

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Provides commands to view the history of locally saved SpecStory sessions and to read the content of a specific session file. Local sessions are stored in the `.specstory/history/` directory in JSON format.

```bash
# View local session history
ls -la .specstory/history/

# Example output:
# -rw-r--r--  1 user  staff  45231 Dec 16 14:35 2025-12-16T14-30-45-abc123.json
# -rw-r--r--  1 user  staff  23156 Dec 15 09:20 2025-12-15T09-15-22-def456.json
# -rw-r--r--  1 user  staff  67890 Dec 14 16:50 2025-12-14T16-45-10-ghi789.json

# Read a specific session
cat .specstory/history/2025-12-16T14-30-45-abc123.json | jq .
```

--------------------------------

### Sync Session API

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Synchronizes a local session file to the cloud.

```APIDOC
## POST /v1/sessions/sync

### Description
Uploads a local SpecStory session file to the cloud, making it available for remote access and search.

### Method
POST

### Endpoint
/v1/sessions/sync

### Parameters
#### Request Body
- **session_data** (file) - Required - The content of the local session JSON file (e.g., from `.specstory/history/`).

### Request Example
```bash
curl -X POST https://api.specstory.com/v1/sessions/sync \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d @.specstory/history/2025-12-16T14-30-45-abc123.json
```

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier of the synced session.
- **synced_at** (string) - The timestamp when the session was synced (ISO 8601 format).

#### Response Example
```json
{
  "session_id": "abc123",
  "synced_at": "2025-12-16T14:35:00Z"
}
```
```

--------------------------------

### Configure VS Code IDE Extension (JSON)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Configures the SpecStory extension in VS Code, including auto-sync preferences, sync intervals, local path settings, and patterns to exclude from synchronization. It also lists commands for manual sync and viewing local history.

```json
{
  "specstory.autoSync": true,
  "specstory.syncInterval": 300,
  "specstory.localPath": ".specstory/history/",
  "specstory.excludePatterns": [
    "node_modules/**",
    ".git/**"
  ]
}
```

--------------------------------

### Extract User Prompts from Session JSON (Bash/jq)

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Extracts the content of messages with the role 'user' from a JSON session file. This command uses `cat` to pipe the file content to `jq` for JSON parsing and filtering.

```bash
cat .specstory/history/2025-12-16T14-30-45-abc123.json | jq '.messages[] | select(.role == "user") | .content'
```

--------------------------------

### User Authentication API

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Authenticates a user and returns an access token for subsequent API requests.

```APIDOC
## POST /v1/auth/login

### Description
Authenticates a user with their email and password to obtain an access token.

### Method
POST

### Endpoint
/v1/auth/login

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "secure_pass"
}
```

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **expires_at** (string) - The expiration time of the token (ISO 8601 format).

#### Response Example
```json
{
  "token": "eyJhbGc...",
  "expires_at": "2025-12-17T14:30:45Z"
}
```
```

--------------------------------

### Session Search API

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Searches for sessions based on various criteria like query, project, and date range.

```APIDOC
## GET /v1/sessions/search

### Description
Searches for AI coding sessions based on keywords, project name, and date filters.

### Method
GET

### Endpoint
/v1/sessions/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **project** (string) - Optional - The name of the project to filter sessions by.
- **date_from** (string) - Optional - The start date for the search (YYYY-MM-DD).
- **date_to** (string) - Optional - The end date for the search (YYYY-MM-DD).

#### Request Body
- **query** (string) - Required - The search query string.
- **project** (string) - Optional - The name of the project to filter sessions by.
- **date_from** (string) - Optional - The start date for the search (YYYY-MM-DD).
- **date_to** (string) - Optional - The end date for the search (YYYY-MM-DD).

### Request Example
```json
{
  "query": "authentication implementation",
  "project": "myapp",
  "date_from": "2025-12-01",
  "date_to": "2025-12-31"
}
```

### Response
#### Success Response (200)
- **sessions** (array) - An array of matching session objects.
- **total** (integer) - The total number of matching sessions found.
- **page** (integer) - The current page number of the results.

#### Response Example
```json
{
  "sessions": [...],
  "total": 15,
  "page": 1
}
```
```

--------------------------------

### SpecStory Cloud Sync Operations

Source: https://context7.com/specstoryai/getspecstory/llms.txt

Manages authentication and synchronization of local SpecStory sessions with the cloud. Users can log in to enable cloud sync, check their login status, manually sync sessions, and log out to disable cloud sync. Logged-in sessions are automatically synced.

```bash
# Login to SpecStory Cloud (enables cloud sync)
specstory login

# This will:
# 1. Open a browser window for authentication
# 2. Store credentials locally
# 3. Enable automatic cloud sync for future sessions

# Verify login status
specstory whoami
# Output: Logged in as user@example.com

# Run an agent with automatic cloud sync (when logged in)
specstory run claude
# Sessions now auto-sync to cloud.specstory.com

# Manually sync existing local sessions to cloud
specstory sync

# This uploads all sessions from .specstory/history/
# that haven't been synced yet

# Example sync output:
# Syncing sessions...
# ✓ 2025-12-16T14-30-45-abc123.json
# ✓ 2025-12-15T09-15-22-def456.json
# ✓ 2025-12-14T16-45-10-ghi789.json
# Synced 3 sessions successfully

# Logout from SpecStory Cloud
specstory logout
# After logout, sessions save locally only (no cloud sync)
```
Tokens:
Raw