# SpecStory Documentation > Official documentation for SpecStory - the AI development workflow platform that preserves the intent behind code generation. This document contains the full content of all documentation pages for AI consumption. For complete information about the company, blog articles, and careers, see https://specstory.com/llms-full.txt --- ## AIrgap **URL:** https://docs.specstory.com/airgap **Description:** Lightweight, Git-native guardrails for AI-assisted coding and open source contributions. AIrgap is a **lightweight, Git-native guardrail system** for your codebase that enforces **modification boundaries** so developers and AI assistants only change what they're supposed to. ## Why AIrgap Exists Software development has changed dramatically with two key trends: 1. **AI-assisted coding is everywhere** - GitHub Copilot, Claude Code, Cursor, and others are now part of daily workflows. Over 75% of developers use them, but studies show around one-third of AI-generated code contains security vulnerabilities. 2. **Open Source contributions are surging** - Events like Hacktoberfest drive thousands of new contributors to projects every year. While exciting for growth, it's challenging for maintainers who face spam PRs, edits to production configs, or risky changes to authentication logic. Without guardrails, AI can "helpfully" rewrite your authentication logic or tweak production configs without you noticing. Existing tools like `CODEOWNERS`, GitHub's rulesets, or branch protections help, but they don't catch unsafe changes early; they operate at review or merge time. ## How AIrgap Works AIrgap runs `git diff` to detect changes in **sub-second time** even on large repos, then validates changes against your rules defined in a `.airgap` file using patterns similar to `.gitignore`. ### Protection Levels - **`!pattern`** → **Full Protection** (no add/modify/delete) - **`~pattern`** → **Protect Existing** (cannot modify/delete existing files, but can add new ones) - **`pattern`** → **Allow** (changes are safe) This makes it flexible enough for everything from critical-path protection to feature-branch isolation. ## Getting Started ### 1. Install AIrgap ```bash curl -L [release-path] -o airgap chmod +x airgap sudo mv airgap /usr/local/bin/ ``` ### 2. Create a `.airgap` file AIrgap uses `.airgap` config files with familiar gitignore-style patterns: ```bash # Protect sensitive areas (no changes allowed here) !src/auth/** !src/payments/** !config/prod/** # Don't touch legacy code, but allow new files in the directory ~src/legacy/** # Safe areas for development src/features/** tests/** ``` ### 3. Validate your changes ```bash airgap # Check staged changes against HEAD airgap --base main # Compare with main branch airgap --json # JSON output for CI ``` Now try editing in the features directory and then the auth directory. For changes in the features directory you'll see: ``` ✅ Change allowed: src/features/search/index.js ``` But any changes in the auth directory will throw this error: ``` ❌ Protected file modified: src/auth/login.js (rule: !src/auth/**) ``` ## Enforcement Everywhere AIrgap is flexible and can run anywhere code is written or reviewed, catching violations as early as possible. ### Local Git Hooks Catch problems before a commit even lands in Git history: ```bash # .git/hooks/pre-commit #!/bin/bash if ! airgap; then echo "❌ Protected files modified!" exit 1 fi ``` ### CI/CD Pipelines Integrate into GitHub Actions, GitLab CI, or any CI system: ```yaml - name: Validate Code Changes run: | airgap --base ${{ github.base_ref }} --json ``` Example JSON output for CI integration: ```json { "status": "fail", "violations": [ { "file": "src/auth/login.js", "rule": "!src/auth/**", "reason": "Protected file modified" } ] } ``` ### AI Assistant Integration Wire AIrgap directly into your AI assistant's workflow. For Claude Code with SpecStory, you can configure a validation hook that runs after each AI interaction: ```json { "hooks": { "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "airgap" }] }] } } ``` This means the moment an AI coding assistant tries to generate code in a protected path, the operation is stopped through guardrails. ### Feature-Specific Validation Create named config files for different contexts: ```bash # .airgap.search-feature !** # Lock everything src/search/** # Allow only search module tests/search/** # And its tests docs/search.md # And documentation ``` Then validate changes against it: ```bash airgap search-feature ``` ## AIrgap vs. Existing Tools | Feature | **AIrgap** | **CODEOWNERS** | **Branch Protection** | **Push Rules** | |---------|------------|----------------|----------------------|----------------| | **Instant feedback** | Pre-commit & CI | Only after PR | After push | After push | | **Works locally** | ✅ Dev machine + AI tools | ❌ | ❌ | ❌ | | **AI assistant integration** | ✅ Native hooks | ❌ | ❌ | ❌ | | **Granular protection** | ✅ Full/existing/allow | ❌ Review routing only | ❌ Binary toggle | ✅ Path restrictions | | **Setup time** | 2 minutes | ~10 minutes | ~20 minutes | Org-admin setup | | **VCS agnostic** | ✅ Works anywhere Git runs | ❌ GitHub only | ❌ GitHub only | ❌ Platform-specific | AIrgap is not a replacement but a **complement**. Think of AIrgap as the *first line of defense*, with CODEOWNERS and rulesets as your *second line*. AIrgap catches issues early and keeps developers productive while providing layered protection. ## Perfect Complement to SpecStory AIrgap works seamlessly with SpecStory's AI conversation management: - **SpecStory captures the "why"** behind code changes through AI conversation history - **AIrgap ensures the "what"** happens within safe boundaries through modification rules - Together, they provide complete visibility and control over AI-assisted development When using SpecStory with Cursor, VS Code + Copilot, or Claude Code, AIrgap can validate that the code changes resulting from your captured AI conversations don't violate your project's protection rules. ## Learn & Contribute - 📖 **Documentation:** Complete setup guides and advanced configuration options - 🤝 **Contribute on GitHub:** AIrgap is open source - contribute examples, report issues, or submit improvements - 🧭 **See it in action:** Try protecting your critical paths with AIrgap and experience how it changes your development flow --- *AIrgap is open source. Use it, adapt it, and help build safer AI-assisted development for everyone.* --- ## FAQs **URL:** https://docs.specstory.com/faqs **Description:** Frequently asked questions about SpecStory. --- ## Overview **URL:** https://docs.specstory.com SpecStory is the **intent layer** for modern software development. It automatically saves your AI conversations across tools as clean markdown. This preserves the **reasoning**, **decisions**, and **design tradeoffs** behind your code, turning the conversations into **versioned**, **reusable**, **shareable**, and git-friendly knowledge. ## Why SpecStory exists Software development has shifted from being purely code-centric to **conversation-driven**. The real design happens in iterative discussions with **AI assistants** and **teammates**: evaluating tradeoffs, debugging edge cases, rejecting alternatives, and shaping architecture. But today, those conversations disappear once tools or sessions end. The result: lost context, repeated prompts, and no traceability for teams and organizations. SpecStory addresses this gap by: - Capturing developer intent as markdown alongside your code. - Making reasoning reusable and portable across tools, projects, and time. - Enabling collaboration and onboarding with shared decision logs. - Preserving privacy with local-first defaults and explicit sharing. In short, the most valuable artifact in modern development is not just the code, but the **story behind it**. SpecStory ensures that story is **never lost**. ## Get Started Choose your path based on how you work: ## What SpecStory does - **Preserve intent:** Automatically capture AI conversations in Markdown. - **Make knowledge reusable:** Search, reference, and build on prior problem-solving. - **Share selectively:** Publish a conversation as a URL when you choose. - **Derive rules for AI:** Generate and maintain project rules from your previous chats. - **Stay private:** Nothing leaves your machine unless you explicitly share or opt in. ## Why developers adopt it - **Works where you already code:** Cursor, VS Code + Copilot, Claude Code, Cursor CLI, Codex CLI and Gemini CLI. - **Git-friendly Markdown:** History lives in your repo alongside code. - **Frictionless start:** No sign-in required for auto-save and manual save. - **Future-proof:** Designed to scale from individuals to teams to orgs. ## From Git for Code to Git for Reasoning Git solved _what changed_ in code. SpecStory solves _why it changed_. --- ## Data Privacy **URL:** https://docs.specstory.com/privacy **Description:** Transparency into what we collect and access to deliver SpecStory ## Services we use to collect data We use [PostHog](https://posthog.com/) to collect product analytics. When you install the SpecStory Extension tracking is turned on by default. You may turn it off in settings via: `specstory.helpUsImprove`. - We log events including: when the extension is activated, when an auto-save occurs, when a manual save occurs, when a share occurs, when a custom rule is derived and when errors occur. - We use this telemetry to calculate total installs, active user counts and to understand other patterns like user retention. We also use [PostHog](https://posthog.com/) to collect web analytics, both on Specstory.com and share.specstory.com. - We use log events to understand time on site, improve usability in our share experience and monitor our own traffic and traffic to shares. - If you turn off `specstory.helpUsImprove` in the Extension settings it will not apply to the web analytics we collect. In SpecStory `v0.7.0` and later for the _optional_ and Derived Rules feature, we use: - [Clerk.com](https://clerk.com/): for authentication and user management. - [Helicone.com](https://www.helicone.ai/): for LLM observability. ## What data is accessed and collected in the SpecStory extension (by feature) ### Auto-saves and manual saves Each of these features read from your local chat history stored in a `sqlite3 state.vscdb`, `chat.jsons`, or Claude Code session files in different folders depending on your OS on your machine. These saves are then stored in your project's `.specstory` folder. ### Shares This feature allows you to publish your local chat history to share.specstory.com. We store shares in [Cloudflare R2 Object Storage](https://www.cloudflare.com/developer-platform/products/r2/). - Shared content is anonymous in the sense that we do not require authentication to share. But it is _public_. - We generate a non-guessable UUID for every share at the time of creation. - When you share your history, the request includes a `device_id hash` from your machine. This allows us to allow you to uniquely edit it without being authenticated. - As an editor, you can delete sensitive information in the share. You may also request full deletion of the object by e-mailing support the URL of the share. ### Derived Rules This feature allows you to save time and improve code generation quality. - When you authenticate into the Extension and turn on the feature, as you prompt we send your prompt history, prior derived rules, file headers and project directory metadata to an LLM. - We log these requests via Helicone by user to track cost, response quality, error rates and prevent abuse. - We conduct aggregate analysis on the requests made by users of this feature to improve it. --- ## Quickstart **URL:** https://docs.specstory.com/quickstart **Description:** 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. Latest CLI updates: see the [SpecStory CLI changelog](https://github.com/specstoryai/getspecstory/releases). ## 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`. ### Verify autosave 1. Chat with Cursor’s AI in a workspace folder. 2. Check `/.specstory/history/` for a Markdown file representing your session. 👉 Learn more in [**Integrations → VS Code + Copilot**](/integrations/cursor). ## 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 `/.specstory/history/` for a new Markdown file. 👉 More details in [**Integrations → VS Code + Copilot**](/integrations/vscode). ## Terminal Coding Agents Wrap your terminal-based AI assistant with SpecStory to capture a Markdown history of the entire chat and tool output. [Dive deeper →](/integrations/claude-code) [Dive deeper →](/integrations/cursor-cli) [Dive deeper →](/integrations/codex-cli) [Dive deeper →](/integrations/droid-cli) [Dive deeper →](/integrations/gemini-cli) Generated files appear in `/.specstory/history/`. 👉 Explore the full overview in [**Integrations → Terminal Coding Agents**](/integrations/terminal-coding-agents/index) or open the dedicated guides for [Claude Code](/integrations/claude-code), [Cursor CLI](/integrations/cursor-cli), [Codex CLI](/integrations/codex-cli), [Droid CLI](/integrations/droid-cli), and [Gemini CLI](/integrations/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**](/integrations/cursor) for storage paths and known issues, or contact [support@specstory.com](mailto:support@specstory.com). ## Next steps - Learn the **core features**: [Auto-save, Share, Derived Rules](/specstory/features). - Configure **settings** and analytics: [Extension & CLI Settings](/specstory/settings). - Explore **editor notes and paths**: [Integrations](/integrations/cursor). --- ## Getting Started **URL:** https://docs.specstory.com/started **Description:** You don't write prompts. You author intent. Enhance your AI development workflow with SpecStory. Use our free extensions for [Cursor](/specstory/introduction#cursor), [VSCode](/specstory/introduction#vs-code-copilot), [Claude Code](/specstory/introduction#cli-for-claude-code), Cursor CLI, Codex CLI and Gemini CLI to save, search and share your AI chat history. Start from where you are today and turn your prompts and AI chats into reusable, shareable assets. ## We work where you do ### Already using AI IDEs? Make them better. AI-generated code lacks context. Without preserved prompts, you lose the "why" behind the "what." Install our free extensions to save, share, and ship with intent, keeping prompts and code together so AI output makes sense.
Cursor Cursor
VSIX Extension
Copilot VSCode + Copilot
VSIX Extension
Claude Claude Code
Mac/Linux/WSL Binary
## Why Preserving Intent Matters Saving your prompts and specs along with your code isn't just about documentation. It's about unlocking the full potential of AI-first development. ## How It Works

Chat with AI

Use Cursor, VSCode+Copilot, or Claude Code as usual

Save

SpecStory saves your prompts and AI responses automatically

Generate Specs

Transform conversations into reusable specifications

Share and Evolve

Build team knowledge and auto-generate AI rules

## Stay Connected Follow us for updates, tips, and AI development insights:
Twitter LinkedIn
--- ## Available Skills **URL:** https://docs.specstory.com/agent-skills/available-skills **Description:** Browse all available Agent Skills for analyzing and organizing your SpecStory session histories. All skills work with your local `.specstory/history` directory. Install them with: ```bash npx skills add specstoryai/agent-skills ``` ## Session Analysis Skills for extracting insights from your AI coding sessions. ### specstory-yak **Detect rabbit holes and scope creep** Analyze your SpecStory AI coding sessions for yak shaving - when your initial goal got derailed into rabbit holes. Get a detailed report of how your session evolved and whether you stayed on track. ``` "Analyze my yak shaving for the last 30 days" "Check for rabbit holes in my recent sessions" "How distracted was I this week?" ``` ### specstory-session-summary **Generate standup-ready summaries** Summarize recent SpecStory AI coding sessions in standup format. Perfect for quickly reviewing what you accomplished and preparing for team updates. ``` "Summarize my coding sessions from this week" "What did I work on yesterday?" "Give me a standup summary for the last 3 days" ``` ### specstory-link-trail **Track all URLs fetched** Review SpecStory AI coding sessions and create a summary of all URLs that were fetched. Useful for auditing external resources accessed during development. ``` "What URLs did I visit in my last session?" "Show me all links fetched this week" "Create a link trail for my recent sessions" ``` ### specstory-project-stats **Fetch project statistics** Fetch project statistics from SpecStory's cloud platform. Get insights about your project's AI-assisted development activity. ``` "Get project stats from SpecStory" "Show my SpecStory project statistics" ``` --- ## Organization & Maintenance Skills for keeping your session history organized and secure. ### specstory-organize **Organize into year/month folders** Organizes SpecStory AI coding sessions in the project's `.specstory/history` directory into year and month subfolders. Keeps your history clean and navigable. ``` "Organize my specstory history folder" "Sort my session files by date" "Clean up my .specstory directory" ``` ### specstory-guard **Pre-commit hook for secrets** Install a pre-commit guardrail for SpecStory AI coding sessions that scans `.specstory/history` for potential secrets and sensitive data before committing. ``` "Set up secret scanning for my specstory files" "Install the specstory guard hook" "Protect my history from accidental secret commits" ``` --- ## Contributing Have an idea for a new skill? Found a way to improve an existing one? The repository welcomes contributions for: - New analysis skills - Improved organization tools - Bug fixes and enhancements - Documentation improvements --- ## Overview **URL:** https://docs.specstory.com/agent-skills **Description:** Extend your AI coding assistant with specialized skills for analyzing, organizing, and extracting insights from your SpecStory session histories. --- ## Installation **URL:** https://docs.specstory.com/agent-skills/installation **Description:** Multiple ways to install Agent Skills for your AI coding assistant. Choose the installation method that best fits your workflow. ## Option 1: Skills CLI (Recommended) Use [npx skills](https://skills.sh) to install skills directly: ```bash # Install all skills npx skills add specstoryai/agent-skills # Install specific skills npx skills add specstoryai/agent-skills --skill specstory-yak specstory-session-summary # List available skills npx skills add specstoryai/agent-skills --list ``` This installs skills to `.agents/skills/` and symlinks them to each detected agent's directory: - `.claude/skills/` - `.cursor/skills/` - `.codex/skills/` ## Option 2: Claude Code Plugin If you use Claude Code, install via its built-in plugin system: ```bash # Add the marketplace /plugin marketplace add specstoryai/agent-skills # Install all SpecStory skills /plugin install specstory-skills ``` ## Option 3: Clone and Copy Clone the entire repo and copy the skills folder: ```bash git clone https://github.com/specstoryai/agent-skills.git cp -r agent-skills/skills/* .claude/skills/ ``` ## Option 4: Git Submodule Add as a submodule for easy updates: ```bash git submodule add https://github.com/specstoryai/agent-skills.git .claude/agent-skills ``` Then reference skills from `.claude/agent-skills/skills/`. ## Option 5: Fork and Customize 1. Fork the [agent-skills repository](https://github.com/specstoryai/agent-skills) 2. Customize skills for your specific needs 3. Clone your fork into your projects This is ideal if you want to: - Modify existing skills - Add private skills not suitable for public sharing - Maintain a consistent set of skills across your organization ## Verifying Installation After installation, verify skills are available by asking your AI assistant: ``` "What SpecStory skills do I have installed?" ``` Or check the skills directory directly: ```bash ls .claude/skills/ # or ls .agents/skills/ ``` ## Next Steps - See [Available Skills](/agent-skills/available-skills) for the full list - [Contribute](https://github.com/specstoryai/agent-skills/blob/main/CONTRIBUTING.md) your own skills --- ## Authentication **URL:** https://docs.specstory.com/api-reference/authentication The SpecStory Cloud API uses **JWT Bearer token authentication** for all requests. You'll need to include your API key in the `Authorization` header of every request. ## Getting Your API Key 1. **Sign in** to [SpecStory Cloud](https://cloud.specstory.com) 2. **Navigate** to Settings → API Keys 3. **Generate** a new API key for your application 4. **Copy** the generated token securely ## Making Authenticated Requests Include your API key in the `Authorization` header using the `Bearer` scheme: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://cloud.specstory.com/api/v1/projects ``` ### Request Headers ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json Accept: application/json ``` ## Authentication Examples ## Environment Variables For security and convenience, store your API key as an environment variable: ## Authentication Errors The API returns specific error codes for authentication issues: ### 401 Unauthorized Returned when no authentication token is provided or the token is invalid: ```json { "success": false, "error": "Invalid session token" } ``` **Common causes:** - Missing `Authorization` header - Invalid or expired API key - Malformed Bearer token format ### 403 Forbidden Returned when the authenticated user doesn't have permission for the requested resource: ```json { "success": false, "error": "Insufficient permissions" } ``` **Common causes:** - Attempting to access another user's projects or sessions - API key doesn't have required permissions ## API Key Management ### Best Practices ### Revoking API Keys To revoke an API key: 1. **Sign in** to [SpecStory Cloud](https://cloud.specstory.com) 2. **Navigate** to Settings → API Keys 3. **Find** the key you want to revoke 4. **Click** the "Revoke" button 5. **Confirm** the revocation ## Testing Authentication You can test your authentication setup with a simple request to list your projects: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://cloud.specstory.com/api/v1/projects ``` A successful response indicates your authentication is working correctly: ```json { "success": true, "data": { "projects": [...], "total": 5 } } ``` ## GraphQL Authentication GraphQL requests use the same Bearer token authentication: ```bash curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "{ projects { id name } }"}' \ https://cloud.specstory.com/api/v1/graphql ``` The interactive GraphQL playground at `https://cloud.specstory.com/api/v1/graphql` also supports authentication - just add your Bearer token in the headers section. --- ## Error Handling **URL:** https://docs.specstory.com/api-reference/errors The SpecStory Cloud API uses conventional HTTP response codes to indicate the success or failure of an API request. Error responses include detailed information to help you understand and resolve issues. ## HTTP Status Codes ### Success Codes | Code | Status | Description | |------|--------|-------------| | `200` | OK | Request succeeded | | `304` | Not Modified | Resource hasn't changed (ETag match) | ### Client Error Codes | Code | Status | Description | |------|--------|-------------| | `400` | Bad Request | Invalid request format or parameters | | `401` | Unauthorized | Missing or invalid authentication | | `403` | Forbidden | Insufficient permissions | | `404` | Not Found | Resource doesn't exist | | `429` | Too Many Requests | Rate limit exceeded | ### Server Error Codes | Code | Status | Description | |------|--------|-------------| | `500` | Internal Server Error | Unexpected server error | | `502` | Bad Gateway | Temporary server issue | | `503` | Service Unavailable | Server temporarily unavailable | ## Error Response Format All error responses follow a consistent JSON structure: ```json { "success": false, "error": "Descriptive error message" } ``` ### Example Error Responses ## Authentication Errors ### 401 Unauthorized **Causes:** - Missing `Authorization` header - Invalid or expired API key - Malformed Bearer token **Solutions:** - Verify your API key is correct - Check the Authorization header format: `Bearer YOUR_API_KEY` - Generate a new API key if the current one is expired ### 403 Forbidden **Causes:** - Attempting to access another user's resources - API key lacks required permissions - Resource access restrictions **Solutions:** - Verify you're accessing your own projects/sessions - Check API key permissions in the dashboard - Ensure the resource ID is correct ## Resource Errors ### 404 Not Found **Common scenarios:** ## Rate Limiting ### 429 Too Many Requests The API implements rate limiting to ensure service quality: - **REST API**: 1000 requests per hour - **GraphQL API**: 500 queries per hour **Rate limit headers:** ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200 ``` **Handling rate limits:** ## GraphQL Errors GraphQL errors are returned in the `errors` array alongside any partial data: ```json { "data": { "project": null }, "errors": [ { "message": "Project not found", "locations": [{"line": 2, "column": 3}], "path": ["project"], "extensions": { "code": "NOT_FOUND", "projectId": "invalid-id" } } ] } ``` ### Common GraphQL Error Codes | Code | Description | Solution | |------|-------------|----------| | `UNAUTHENTICATED` | Missing or invalid authentication | Check Authorization header | | `FORBIDDEN` | Insufficient permissions | Verify resource access | | `NOT_FOUND` | Resource doesn't exist | Check resource ID | | `VALIDATION_ERROR` | Invalid query or variables | Review query syntax | | `RATE_LIMITED` | Too many requests | Implement backoff strategy | ## Validation Errors ### 400 Bad Request **Request validation failures:** ## Error Handling Best Practices ### Implement Retry Logic ```javascript async function apiRequest(url, options, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { const response = await fetch(url, options); // Success if (response.ok) { return await response.json(); } // Client errors (4xx) - don't retry if (response.status >= 400 && response.status < 500) { const error = await response.json(); throw new Error(error.error); } // Server errors (5xx) - retry with backoff if (attempt === maxRetries) { throw new Error(`Request failed after ${maxRetries} attempts`); } // Exponential backoff const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } catch (error) { if (attempt === maxRetries) { throw error; } } } } ``` ### Log Errors for Debugging ```javascript function handleApiError(error, context) { console.error('API Error:', { message: error.message, context: context, timestamp: new Date().toISOString(), stack: error.stack }); // Report to error tracking service // errorTracker.captureException(error, { context }); } ``` ### Graceful Degradation ```javascript async function getProjectSessions(projectId) { try { const response = await fetch(`/api/v1/projects/${projectId}/sessions`); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { console.warn('Failed to load sessions:', error.message); // Return empty state instead of crashing return { success: true, data: { sessions: [], total: 0, projectId: projectId } }; } } ``` ## Troubleshooting Checklist When encountering API errors: 1. **Check Authentication** - Verify API key is valid and not expired - Ensure proper Authorization header format - Test with a simple request like `GET /api/v1/projects` 2. **Validate Request Format** - Check JSON syntax and structure - Verify required fields are included - Ensure parameter values are within allowed ranges 3. **Review Resource Access** - Confirm resource IDs exist and are accessible - Check if you have permissions for the operation - Verify project/session relationships 4. **Monitor Rate Limits** - Check rate limit headers in responses - Implement appropriate backoff strategies - Consider caching frequently accessed data 5. **Test with GraphQL Playground** - Use the interactive playground to test queries - Validate GraphQL syntax and variables - Explore schema documentation for available fields ## Getting Help If you're still experiencing issues: - **Check our status page** for service incidents - **Search existing issues** on [GitHub](https://github.com/specstoryai/getspecstory/issues) - **Contact support** at [support@specstory.com](mailto:support@specstory.com) - **Join our community** on [Slack](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg) Include the following information when reporting issues: - Request URL and method - Request headers and body - Response status code and body - Timestamp of the request - Your API key ID (not the full key) --- ## GraphQL Endpoint **URL:** https://docs.specstory.com/api-reference/graphql-endpoint **Description:** Execute GraphQL queries for advanced data retrieval and search ## Request ## Response --- ## GraphQL Examples **URL:** https://docs.specstory.com/api-reference/graphql-examples **Description:** Practical GraphQL query examples for the SpecStory Cloud API - search, filter, and retrieve your AI conversation data efficiently ## Basic Queries ### List All Projects ```graphql query GetProjects { projects { id name icon color createdAt updatedAt sessionCount } } ``` ### Get Project with Sessions ```graphql query GetProjectWithSessions($projectId: ID!) { project(id: $projectId) { id name icon color sessions(limit: 10) { id name createdAt markdownSize metadata { clientName llmModels tags } } } } ``` **Variables:** ```json { "projectId": "your-project-id" } ``` ## Search Queries ### Full-Text Search Across Sessions ```graphql query SearchSessions($query: String!, $limit: Int = 10) { searchSessions(query: $query, limit: $limit) { total results { id name project { id name } rank snippet createdAt metadata { llmModels tags } } } } ``` **Variables:** ```json { "query": "React components", "limit": 20 } ``` ### Search with Filters ```graphql query FilteredSearch($query: String!, $filters: SessionFilters!) { searchSessions(query: $query, filters: $filters, limit: 15) { total results { id name project { name } rank snippet createdAt metadata { clientName llmModels gitBranches tags } } } } ``` **Variables:** ```json { "query": "API documentation", "filters": { "projectIds": ["project-1", "project-2"], "llmModels": ["claude-3-opus", "gpt-4"], "tags": ["documentation", "api"], "dateRange": { "start": "2024-01-01T00:00:00Z", "end": "2024-12-31T23:59:59Z" } } } ``` ## Advanced Filtering ### Sessions by LLM Model ```graphql query SessionsByModel($model: String!, $projectId: ID) { sessions( filters: { llmModels: [$model] projectId: $projectId } orderBy: CREATED_AT_DESC limit: 25 ) { id name createdAt markdownSize project { name icon } metadata { llmModels clientName gitBranches } } } ``` **Variables:** ```json { "model": "claude-3-opus", "projectId": "your-project-id" } ``` ### Recent Sessions with Git Context ```graphql query RecentSessionsWithGit($days: Int = 7) { sessions( filters: { createdAfter: $days hasGitBranches: true } orderBy: CREATED_AT_DESC limit: 20 ) { id name createdAt project { name color } metadata { gitBranches llmModels clientName tags } } } ``` **Variables:** ```json { "days": 14 } ``` ## Aggregation Queries ### Project Statistics ```graphql query ProjectStats($projectId: ID!) { project(id: $projectId) { id name stats { totalSessions totalMarkdownSize totalRawDataSize uniqueLLMModels uniqueGitBranches sessionsByDay(days: 30) { date count } topTags(limit: 10) { tag count } } } } ``` ### Usage Analytics ```graphql query UsageAnalytics($timeRange: TimeRange!) { analytics(timeRange: $timeRange) { totalSessions totalProjects sessionsByModel { model count totalSize } sessionsByClient { client count averageSize } activityByDay { date sessions projects } } } ``` **Variables:** ```json { "timeRange": { "start": "2024-01-01T00:00:00Z", "end": "2024-01-31T23:59:59Z" } } ``` ## Practical Use Cases ### Building a Dashboard ```graphql query DashboardData { # Recent activity recentSessions: sessions(limit: 5, orderBy: CREATED_AT_DESC) { id name createdAt project { name icon color } metadata { llmModels } } # Project overview projects { id name icon color sessionCount lastActivity } # Quick stats stats { totalSessions totalProjects sessionsThisWeek topLLMModels(limit: 3) { model count } } } ``` ### Export Sessions for Analysis ```graphql query ExportSessions($projectId: ID!, $cursor: String) { project(id: $projectId) { name sessions(first: 100, after: $cursor) { pageInfo { hasNextPage endCursor } edges { node { id name createdAt markdownContent metadata { clientName clientVersion llmModels gitBranches tags } } } } } } ``` ### Find Related Sessions ```graphql query RelatedSessions($sessionId: ID!, $limit: Int = 5) { session(id: $sessionId) { id name relatedSessions(limit: $limit) { id name similarity project { name } createdAt metadata { llmModels tags } } } } ``` ## Error Handling GraphQL errors are returned in the `errors` array: ```json { "data": null, "errors": [ { "message": "Project not found", "locations": [{"line": 2, "column": 3}], "path": ["project"], "extensions": { "code": "NOT_FOUND", "projectId": "invalid-id" } } ] } ``` ## Performance Tips ### Use Fragments for Reusable Fields ```graphql fragment SessionBasics on Session { id name createdAt markdownSize metadata { llmModels tags } } query GetSessions { recentSessions: sessions(limit: 10) { ...SessionBasics } searchResults: searchSessions(query: "React") { results { ...SessionBasics rank snippet } } } ``` ### Pagination for Large Datasets ```graphql query PaginatedSessions($cursor: String, $limit: Int = 20) { sessions(first: $limit, after: $cursor) { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id name createdAt project { name } } } } } ``` ### Field Selection Only request the fields you need to minimize response size and improve performance: ```graphql # Good - specific fields query OptimizedQuery { projects { id name sessionCount } } # Avoid - requesting unnecessary data query UnoptimizedQuery { projects { id name icon color createdAt updatedAt sessionCount sessions { id name markdownContent # Large field metadata } } } ``` ## Schema Introspection Explore the available types and fields: ```graphql query IntrospectSchema { __schema { types { name description fields { name type { name } } } } } ``` Query specific type information: ```graphql query SessionType { __type(name: "Session") { name description fields { name description type { name kind } } } } ``` --- ## Overview **URL:** https://docs.specstory.com/api-reference/graphql **Description:** Advanced querying interface for complex operations, filtering, and full-text search The GraphQL API provides advanced querying capabilities for complex operations, relationship queries, and full-text search across your SpecStory data. Unlike the REST API which is designed for simple CRUD operations, GraphQL excels at retrieving exactly the data you need in a single request. ## POST /api/v1/graphql Execute GraphQL queries for advanced data retrieval, filtering, and search operations. ### Authentication All GraphQL requests require the same Bearer token authentication as the REST API: ```bash curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "{ projects { id name } }"}' \ https://cloud.specstory.com/api/v1/graphql ``` ### Basic Query Structure GraphQL requests are sent as JSON with a `query` field: ### Response Format GraphQL responses follow a standard format: ```json { "data": { "projects": [ { "id": "proj_123", "name": "My Web App", "sessionCount": 15 }, { "id": "proj_789", "name": "Mobile App", "sessionCount": 8 } ] } } ``` ### Variables and Operations For complex queries, use variables to make your queries reusable: ### Key Advantages Over REST **Single Request, Multiple Resources** ```graphql { projects { id name sessions(limit: 3) { id name metadata { llmModels tags } } } } ``` **Precise Field Selection** ```graphql { sessions(limit: 10) { id name # Only get the fields you need createdAt } } ``` **Advanced Filtering** ```graphql { searchSessions( query: "React components" filters: { llmModels: ["claude-3-opus"] dateRange: { start: "2024-01-01T00:00:00Z" end: "2024-01-31T23:59:59Z" } } ) { total results { id name rank snippet } } } ``` ### Error Handling GraphQL errors are returned in the `errors` array alongside any successful data: ```json { "data": { "projects": [...] }, "errors": [ { "message": "Project not found", "locations": [{"line": 2, "column": 3}], "path": ["project"], "extensions": { "code": "NOT_FOUND", "projectId": "invalid-id" } } ] } ``` ### Schema Introspection GraphQL is self-documenting. You can query the schema itself: ```graphql { __schema { types { name description } } } ``` Or get information about specific types: ```graphql { __type(name: "Session") { name fields { name type { name } } } } ``` ## When to Use GraphQL vs REST ### Use GraphQL for: - **Complex queries** involving multiple related entities - **Search operations** with filtering and ranking - **Dashboard data** where you need specific fields from multiple resources - **Mobile applications** where bandwidth efficiency matters - **Exploratory data analysis** where requirements change frequently ### Use REST for: - **Simple CRUD operations** on individual resources - **File uploads** or binary data operations - **Caching scenarios** where HTTP caching is important - **Third-party integrations** that expect REST endpoints ## Advanced Queries For comprehensive examples of complex GraphQL operations, including search, filtering, aggregations, and real-world use cases, see our [GraphQL Examples](/api-reference/graphql-examples) page. The interactive [GraphQL playground](/api/v1/graphql) provides the best way to explore the schema, test queries, and understand the full capabilities of the SpecStory GraphQL API. --- ## Overview **URL:** https://docs.specstory.com/api-reference/introduction **Description:** Complete reference for the SpecStory Cloud API - manage your AI conversation projects and sessions programmatically # SpecStory Cloud API The SpecStory Cloud API provides programmatic access to your AI conversation data, enabling you to build custom integrations, automate workflows, and create powerful applications on top of your SpecStory ecosystem. ## Base URL All API requests should be made to: https://cloud.specstory.com ## API Overview SpecStory Cloud offers two complementary interfaces: ### REST API Perfect for standard CRUD operations on projects and sessions: - **Projects**: Manage workspaces and organize your AI conversations - **Sessions**: Access, retrieve, and manage individual AI conversation sessions - **Metadata**: Rich context including git branches, LLM models, client information, and tags ### GraphQL API Advanced querying interface for complex operations: - **Complex Queries**: Multi-entity queries with relationships - **Advanced Filtering**: Filter sessions by metadata, tags, dates, and more - **Full-Text Search**: Search across session content with relevance ranking - **Efficient Data Fetching**: Request exactly the data you need ## Key Features ### ETag Support Efficient caching and conditional requests using ETags for optimal performance when working with session data. ### Multiple Content Types - **JSON**: Structured data for programmatic access - **Markdown**: Raw conversation content for direct consumption ### Rich Metadata Every session includes comprehensive metadata: - **Client Information**: Name, version, and device details - **Git Context**: Branch information for code-related conversations - **LLM Models**: Track which AI models were used - **Custom Tags**: Organize and categorize your conversations ## Rate Limits The SpecStory Cloud API implements reasonable rate limits to ensure service quality: - **REST API**: 1000 requests per hour per API key - **GraphQL API**: 500 queries per hour per API key Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Your rate limit ceiling for that given request - `X-RateLimit-Remaining`: Number of requests left for the time window - `X-RateLimit-Reset`: UTC epoch seconds when the rate limit resets ## Getting Started 1. **Get your API key** from the [SpecStory Cloud Dashboard](https://cloud.specstory.com/settings/api-keys) 2. **Authenticate** your requests using Bearer token authentication 3. **Start with projects** to understand your workspace organization 4. **Explore sessions** to access your AI conversation data 5. **Try GraphQL** for advanced querying and search capabilities ## SDKs and Libraries While the SpecStory Cloud API is REST and GraphQL based, we're working on official SDKs: - **JavaScript/TypeScript**: Coming soon - **Python**: Coming soon - **Go**: Coming soon In the meantime, you can use any HTTP client or GraphQL library with the API endpoints documented here. ## Support Need help with the API? We're here to assist: - **Documentation Issues**: [File an issue](https://github.com/specstoryai/getspecstory/issues) on GitHub - **API Support**: Email us at [support@specstory.com](mailto:support@specstory.com) - **Community**: Join our [Slack community](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg) --- ## Overview **URL:** https://docs.specstory.com/cloud/overview SpecStory Cloud turns your local `.specstory/history/` into a centralized, searchable knowledge system. Locally, SpecStory captures the reasoning and decisions behind your code. With Cloud, you can sync those reasoning and conversations to one place, making them easier to search, organize, and revisit. ## Why SpecStory Cloud exists Local-first capture is great for individuals, but it leaves with certain challenges: - **Scattered knowledge**: conversations and reasonings sit isolated on different machines. - **Lost context**: onboarding or PR review requires digging through repos and commits. - **No global search**: finding “that one conversation about auth migrations” is slow or impossible. - **Fragile sharing**: passing around or copy-pasting Markdown files doesn’t scale. Cloud solves these problems by indexing your synced sessions in one place. ## What Cloud adds today - **Centralized search** across all synced projects. - **Organized storage** by project and time. - **Private by default**, nothing syncs until you explicitly run it. - **Single-user workspaces** today, team collaboration features are on the roadmap.. - **API endpoints** for programmatic sync and search. ## How It Fits Together 1. **Local Capture:** Cursor, VS Code + Copilot, Claude Code CLI, Gemini CLI, and Codex CLI auto-save conversations to `.specstory/history/`. 2. **Sync to Cloud:** Run `specstory sync` (or the equivalent editor command). The CLI sends each session securely to Cloud. No background uploads without consent. 3. **Centralized Search & Access:** Cloud indexes synced histories for fast search and filtering. Find past decisions and design threads in seconds. 4. **Personal Knowledge Hub:** You can now query across projects and repos in seconds, with context preserved. ## What you can do with Cloud - 🔍 **Search across projects**: Full-text + semantic search, with filters for projects and time range. - ⚙️ **Integrate with CLI & API** to script syncs or query histories. ## Next steps --- ## Cloud Quickstart **URL:** https://docs.specstory.com/cloud/quickstart 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](https://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. ## 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](/specstory/introduction). 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 / Gemini CLI Install the SpecStory CLI and capture terminal agent sessions locally. **macOS (via Homebrew):** ```bash 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 run gemini # launches Gemini CLI and captures the session specstory sync # converts existing sessions to Markdown ``` **Linux/WSL:** Download the latest release from our [GitHub releases](https://github.com/specstoryai/getspecstory/releases) and follow the Linux installation instructions in our [Installation Guide](/specstory/introduction). Run Claude Code through SpecStory: ```bash 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 run gemini # launches Gemini CLI and captures the session specstory sync # converts existing sessions to Markdown ``` ## 3. Authenticate your device for Cloud Run once per machine to allow uploads from the CLI/extension: ```bash specstory login ``` This opens a browser window to complete a secure login. Your device stores a token locally and future syncs use it automatically. ## 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 ```bash # Sync all local sessions in the current repo/project specstory sync # Sync a single session by ID specstory sync claude -s ``` After sync, refresh [cloud.specstory.com](https://cloud.specstory.com), you should see the project and synced sessions. ## 5. Run your first search 1. Open [cloud.specstory.com](https://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. ## 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**](mailto:support@specstory.com). ## Where to next --- ## Search & Organization **URL:** https://docs.specstory.com/cloud/search-and-organization SpecStory Cloud is built to help you **resurface decisions, reasoning, and context** quickly. Once your histories are synced, Cloud indexes them for both **keyword search** and **semantic search** with fast retrieval and accuracy. ## Search Basics - Use the **search bar** at the top of the Cloud dashboard. - Results combine: - **Full-text search** (matches exact words and phrases) - **Semantic search** (finds related meaning, even if phrasing differs) [ON ROADMAP] ## Filters Search can be narrowed down and refined using the filter panel: - **Projects**: Select one or more synced projects. - **Time Range**: Focus results on a specific timeframe (like day-wise, week, or custom). ## Exploring Results Each result shows: - **Title**: Usually derived from the first prompt in the session. - **Snippet**: Preview of matched content with highlights. - **Metadata**: Project name, date, and file location if available. Click a result to open the **full conversation** in context. ## Organizing Knowledge SpecStory Cloud automatically groups sessions: - **Workspace structure**: Sessions are organized by project and sync source when uploaded. --- ## Session Sharing **URL:** https://docs.specstory.com/cloud/session-sharing Session sharing lets you create public links to your AI coding sessions. Share problem-solving approaches, explain architectural decisions, or document debugging workflows with teammates, blog readers, or the community. ## How Sharing Works SpecStory Cloud uses a **persistent sharing model**. When you share a session, you create a live link to that session—not a static snapshot. New exchanges added to the session automatically appear in the shared version. - **Share URL format**: `cloud.specstory.com/share/{sessionId}` - **Public access**: Viewers can access shared sessions without authentication - **Owner control**: You decide what's visible and can revoke access at any time ## Sharing a Session 1. Open a session in [cloud.specstory.com](https://cloud.specstory.com). 2. Click the **Share** button in the session header. 3. In the share modal: - Toggle **Public/Private** to enable or disable sharing. - Copy the share link using the **Copy Link** button. - Optionally hide specific exchanges (see below). - Use **Preview as Viewer** to see exactly what viewers will see. When sharing is enabled, the share link becomes active. Setting the session back to **Private** makes the link return a 404 page. ## Controlling Content Visibility Not every exchange needs to be public. You can selectively hide exchanges that contain sensitive information, tangential discussions, or content you don't want viewers to see. ### Hiding Exchanges - Each exchange has a visibility toggle (eye icon). - Click the toggle to hide an exchange from the shared view. - Hidden exchanges remain visible to you but are excluded from the public view. - The share modal shows a summary: "You've hidden X exchanges." ### What You Can Edit As the session owner, you can: - **Edit the session title** — Provide a clearer name for shared context. - **Edit exchange titles** — For each exchange, provide a custom title. - **Hide/show exchanges** — Control which prompt-response pairs are visible. - **Delete exchanges** — Remove exchanges entirely from the session. ## What Viewers See When someone opens your shared session link, they see: - **Session title** — The name you've given the session. - **Project info** — A small icon and project name for context. - **Author info** — Indicates who shared the session. - **Visible exchanges** — Only exchanges you haven't hidden. - **Table of contents** — Navigation through the session's exchanges. Viewers cannot: - Edit or delete content. - See hidden exchanges. - Access your other sessions or projects. - Download the original session data. ## Privacy and Security Session sharing is designed with privacy as a priority: - **Opt-in only**: Sessions are private by default. Sharing requires explicit action. - **Database-level filtering**: Hidden exchanges are excluded from database queries for the public endpoint—they never leave the server. - **Revocable access**: Set a session back to Private at any time to disable the share link. - **No account required for viewers**: Public links work without authentication, but viewers have read-only access. ## One-Time Sync for Extension Users If you don't have auto-sync enabled in the SpecStory Extension, you can still share sessions: 1. **Share** on a local session (Cmd/Ctrl-Shift-P, `SpecStory: Share AI Chat History`) 2. SpecStory prompts you to log in if needed. 3. A **one-time sync** uploads just that session to the cloud. 4. The session becomes shareable without enabling global auto-sync. To update a shared session, re-share it to trigger another one-time sync. ## Next --- ## Sync & Store **URL:** https://docs.specstory.com/cloud/sync-and-store Sync lets you move those conversation histories into the Cloud for centralized indexing and search. ## How Sync Works 1. **Local Capture:** Editors (Cursor, VS Code + Copilot) and the CLI (Claude Code, Cursor CLI, Codex CLI, Gemini CLI) write Markdown histories into `.specstory/history/`. 2. **Authentication:** You run `specstory login` once per machine to link your device with Cloud. 3. **Manual Sync:** Sync is always explicit - run via the CLI or extension command. 4. **Session Upload:** The CLI or extension uploads sessions one by one. For full-project sync, the CLI scans `.specstory/history/` and calls the API for each session file. 5. **Storage:** Sessions are stored in Cloud as: - **Markdown** (clean, readable capture) - **Raw JSON** (original conversation data) - Both are preserved exactly as generated ## Configuring Sync ### From Cursor or VS Code extensions - Open your project folder (must contain `.specstory/history/`). - Open the Command Palette (`Ctrl/Cmd+Shift+P`). - Run **`SpecStory: Sync with Cloud`**. - The extension authenticates, uploads session files, and shows a completion toast. ### From the CLI (Terminal agents) ```bash # Authenticate device (run once) specstory login # Sync all local sessions in the current repo/project specstory sync # Sync a single session by ID specstory sync -u ``` ## Verifying Your AI-conversations Sync After running sync: - Check the **CLI output** (or toast in extensions) for success. - Refresh [cloud.specstory.com](https://cloud.specstory.com). - You should see your project and sessions listed. - Open a session to confirm content matches your local Markdown. ## Next --- ## SpecFlow **URL:** https://docs.specstory.com/guides/specflow **Description:** A structured methodology for building software with AI coding tools. Plan first, build better. ## Plan First, Build Better AI coding tools are fast. Too fast. Without structure, you end up with code that works but nobody understands, decisions that get lost, and prompts you repeat because you forgot what you already tried. SpecFlow is an opinionated methodology for AI-assisted development. It forces you to think before you prompt, document as you build, and preserve the reasoning that makes code maintainable. The core principle: **the bottleneck in AI-assisted development is not implementation speed, it is specification clarity.** ## The Five Phases 1. **Intent:** Define what you are building and why. Capture goals, constraints, success criteria, and non-goals before writing any code. 2. **Roadmap:** Break the problem into phases with clear deliverables and dependencies. Each phase should be completable in one focused session. 3. **Tasks:** Translate each roadmap phase into atomic tasks. Mark which tasks are human decisions vs. AI-assisted implementation. 4. **Execute:** Work through tasks systematically with your AI tool. Use SpecStory to capture the reasoning and decisions as you go. 5. **Refine:** Review outputs against your original intent. Update the roadmap based on what you learned. Document changes for future reference. --- ## Phase 1: Intent The intent document is the most important artifact in SpecFlow. It prevents scope creep, aligns AI outputs with your goals, and gives you something to check against when you are deep in implementation. Write your intent document before opening your editor. **Rules for a good intent document:** - Success criteria must be testable. "Works well" is not a criterion. "Loads in under 2 seconds" is. - Non-goals are as important as goals. They prevent scope creep and give you permission to say no. - Open questions are honest. If you do not know something, write it down instead of pretending you do. --- ## Phase 2: Roadmap A roadmap breaks your intent into phases you can actually execute. Each phase should have a clear goal, concrete deliverables, and explicit dependencies. Do not plan more than 3-5 phases. If you need more, your project is too big or your phases are too small. **Rules for a good roadmap:** - Each phase should be completable in 1-4 hours of focused work. - Deliverables are nouns, not verbs. "User authentication module" not "implement authentication." - Dependencies must be explicit. If Phase 3 needs Phase 1 but not Phase 2, say so. --- ## Phase 3: Tasks Tasks are the atomic units of work. Each task should be small enough to complete in one AI session and specific enough that you know when it is done. The key insight: not every task should go to AI. Some tasks require human judgment. Label them explicitly. **Rules for good tasks:** - AI-assisted tasks need specific prompts, not vague directions. - Human decision tasks need options and criteria, not just "figure it out." - Every task needs a verification step. If you cannot verify it, the task is too vague. --- ## Phase 4: Execute This is where you actually build. Work through tasks in order, respect dependencies, and capture everything with SpecStory. ### Effective AI Prompting Every prompt to your AI tool should include: 1. **Context**: Where you are in the project (phase, task number) 2. **Specific ask**: Exactly what you need right now 3. **Constraints**: Technical requirements, style preferences, limitations 4. **Output format**: How you want the response structured ### Capture Reasoning with SpecStory As you execute, SpecStory automatically saves your AI conversations to `.specstory/history/`. This is not optional overhead; it is the mechanism that preserves your decisions. When you finish a task: 1. Verify the output matches the task definition 2. Review the conversation in `.specstory/history/` 3. If you made important decisions, ensure they are captured in the transcript For terminal agents (Claude Code, Codex, Cursor CLI, Droid CLI, Gemini CLI), run your session through SpecStory: ```bash specstory run claude # or cursor / codex / droid / gemini ``` Commit `.specstory/history/` alongside your code. Your future self and teammates will thank you. --- ## Phase 5: Refine After each phase, step back and evaluate. Do not just move to the next phase because you finished the tasks. **Questions to ask after each phase:** 1. Does the output match the original intent? (Pull up your intent document and check.) 2. What did you learn that changes the roadmap? 3. Are there new constraints or open questions to document? 4. Should any success criteria be updated? **When to update your documents:** - Small adjustments: Update task details, keep roadmap unchanged - Medium changes: Revise phase goals or reorder phases - Large pivots: Revisit the intent document, possibly redefine success criteria Document what changed and why. This is where SpecStory pays off: you have a record of the reasoning that led to changes. --- ## Full Example: CLI Task Manager Here is a complete SpecFlow walkthrough for a small project. ### Intent ```markdown # Project Intent: CLI Task Manager ## Vision A command-line todo application that stores tasks locally and supports priorities, due dates, and simple filtering. ## Problem Statement I want a fast, keyboard-driven task manager that works offline and integrates with my terminal workflow. Existing GUI apps break my flow. ## Success Criteria - [ ] Add, complete, and delete tasks from command line - [ ] Assign priority (high/medium/low) and optional due date - [ ] List tasks with filters (by priority, by due date, completed/pending) - [ ] Data persists between sessions in a local file - [ ] Installable via npm or single binary ## Constraints - Technical: Node.js, no external database, single JSON file storage - Time: Complete in one weekend (8-10 hours) - Resources: Solo developer ## Non-Goals - No sync across devices - No collaboration features - No mobile or web interface ## Open Questions - JSON vs SQLite for storage? (Leaning JSON for simplicity) ``` ### Roadmap ```markdown # Roadmap: CLI Task Manager ## Phase 1: Foundation (2 hours) **Goal**: Project setup and core data model **Deliverables**: - Initialized Node.js project with TypeScript - Task data model and JSON storage module - Basic CLI argument parsing **Dependencies**: None ## Phase 2: Core Commands (3 hours) **Goal**: Implement add, list, complete, delete **Deliverables**: - `task add "description"` command - `task list` command with table output - `task done ` and `task delete ` commands **Dependencies**: Phase 1 ## Phase 3: Filtering and Priorities (2 hours) **Goal**: Add priority, due dates, and filtering **Deliverables**: - Priority flag on add: `task add "desc" --priority high` - Due date flag: `task add "desc" --due 2024-01-15` - Filter flags: `task list --priority high --pending` **Dependencies**: Phase 2 ## Phase 4: Polish and Package (1.5 hours) **Goal**: Error handling, help text, npm packaging **Deliverables**: - Helpful error messages for invalid input - `--help` output for all commands - package.json configured for npm publish or npx usage **Dependencies**: Phase 3 ``` ### Sample Task Breakdown (Phase 2) ```markdown ## Phase 2 Tasks ### Task 2.1: Add Command [AI-Assisted] **Input**: Storage module from Phase 1 **Action**: Implement `task add "description"` that creates a task with auto-generated ID and saves to JSON **Output**: Working add command, task appears in storage file **Verification**: Run `task add "Test"`, check JSON file contains task ### Task 2.2: List Command [AI-Assisted] **Input**: Storage module, sample tasks in JSON **Action**: Implement `task list` that reads JSON and displays as table **Output**: Formatted table output showing ID, description, status **Verification**: Add 3 tasks, run `task list`, confirm all appear ### Task 2.3: Complete Command [AI-Assisted] **Input**: Working add and list commands **Action**: Implement `task done ` that marks task complete **Output**: Task status changes to "done" in storage **Verification**: Add task, complete it, list shows updated status ### Task 2.4: Delete Command [AI-Assisted] **Input**: Working list command **Action**: Implement `task delete ` that removes task from storage **Output**: Task removed from JSON file **Verification**: Add task, delete it, list no longer shows it ``` ### Execute with SpecStory ```bash cd cli-task-manager specstory run claude ``` In the session: ``` I am building a CLI Task Manager. Currently in Phase 2, Task 2.1. Context: Node.js + TypeScript project with a storage module that reads/writes tasks.json. Task interface: { id, description, status, createdAt }. Task: Implement `task add "description"` command. Constraints: - Use commander.js for CLI parsing (already installed) - Generate ID with nanoid - Status defaults to "pending" - createdAt is ISO timestamp Expected output: The add command implementation in src/commands/add.ts ``` After completing all Phase 2 tasks, commit both the code and the SpecStory history: ```bash git add src/ tasks.json .specstory/ git commit -m "Phase 2: Core commands (add, list, done, delete)" ``` --- ## Common Pitfalls ### Skipping Intent **Symptom**: Requirements keep changing mid-build. You are not sure when you are done. **Fix**: Spend 15 minutes on the intent document before anything else. If you cannot write clear success criteria, you are not ready to build. ### Over-Planning **Symptom**: You have been planning for hours and have not written any code. **Fix**: Time-box planning. Intent: 15 minutes. Roadmap: 15 minutes. Tasks for Phase 1: 10 minutes. Then start executing. ### Vague Tasks **Symptom**: AI outputs do not match what you wanted. You keep reprompting. **Fix**: Every task needs specific inputs, actions, outputs, and verification steps. If your task says "implement authentication," it is too vague. ### Ignoring Dependencies **Symptom**: You build Phase 3 features but Phase 2 is broken. Integration is painful. **Fix**: Complete phases in order. Do not skip ahead because something seems easy. ### Not Capturing Reasoning **Symptom**: You finished the feature but cannot explain why you made certain choices. Onboarding new teammates is painful. **Fix**: Use SpecStory. Commit `.specstory/history/`. Review transcripts before marking phases complete. --- ## Quick Reference ``` SpecFlow Quick Reference ======================== 1. INTENT - What + Why + Success Criteria + Non-Goals 2. ROADMAP - 3-5 Phases with goals, deliverables, dependencies 3. TASKS - Atomic units with input/action/output/verification 4. EXECUTE - Work systematically, capture with SpecStory 5. REFINE - Check against intent, update docs, commit history Prompting Formula: Context + Specific Ask + Constraints + Expected Output Time Budget (small project): Intent: 15 min | Roadmap: 15 min | Tasks: 10 min/phase | Execute: bulk of time Remember: The bottleneck is specification clarity, not implementation speed. ``` --- ## Further Reading - [Beyond Code-Centric Development](https://specstory.com/whitepapers/beyond-code-centric-specstory-2025.pdf) - Whitepaper on why specification clarity matters more than implementation speed. - [SpecFlow on GitHub](https://github.com/specstoryai/specflow) - Examples, templates, and community contributions. - [specflow.com](https://www.specflow.com/) - The full methodology site with additional examples and reference material. --- ## Claude Code **URL:** https://docs.specstory.com/integrations/claude-code [Claude Code](https://docs.anthropic.com/en/docs/claude-code) gives you an AI pair-programmer directly in the terminal. Run it through SpecStory to capture every step of the conversation and reasoning as Markdown that ships with your repo. ## Run Claude Code with SpecStory ```bash specstory run claude ``` While the wrapper is active you can use the full Claude Code feature set, including multi-file edits, `/init`, `/clear`, and slash commands. SpecStory records both sides of the chat plus terminal output generated by `!` commands. ## Sync existing Claude Code sessions Forgot to launch with `specstory run claude`? Convert prior sessions with `specstory sync`. ```bash # Convert everything Claude Code has stored locally specstory sync claude # Export a single session by ID specstory sync claude -s # Inspect sync logs in your terminal specstory sync claude --console ``` - Session sources: Read from `~/.claude/projects/` (JSONL files). The resulting Markdown files live under `.specstory/history/` with timestamps and metadata for easy sharing. ## Watch for Claude Code activity Prefer to run Claude Code directly or via another tool? Use `specstory watch` to watch the current project directory for any new agent activity and auto-save it to markdown. ```bash # Watch for only activity from any supported coding agent specstory watch # Watch for only new Claude Code agent activity specstory watch claude ``` Run `specstory watch` without an agent name to capture activity from any supported provider. ## Best Practices - **Segment workstreams**: Sstart fresh sessions per task so transcripts stay focused. - **Create `CLAUDE.md`**: Seed the assistant with project docs once, and re-use those instructions automatically. - **Keep sessions focused**: Use `/clear` between tasks so transcripts stay tight and portable. - **Archive transcripts**: Commit `.specstory/history/` alongside your code to preserve design intent. ## Troubleshooting - `claude` command missing: Run `claude --version` outside SpecStory to verify installing Anthropic's CLI. - No Markdown output: Make sure you start `specstory run claude` inside a writable project folder. - `specstory sync` finds nothing: Claude Code must have an existing session database in the current directory. - Need help? Reach out at [support@specstory.com](mailto:support@specstory.com) or open an issue on [GitHub](https://github.com/specstoryai/getspecstory/issues). --- ## Codex **URL:** https://docs.specstory.com/integrations/codex-cli [Codex CLI](https://github.com/openai/codex) gives you AI-powered code code generation and reasoning straight from the terminal. Pair it with SpecStory to preserve every AI-powered coding session and intent as Markdown. ## Run Codex CLI with SpecStory ```bash specstory run codex ``` You can continue to use Codex CLI features such as multi-file diffs, auto PRs, and test runs while SpecStory records the conversation and shell context. ## Sync older Codex CLI sessions If you used Codex CLI before installing SpecStory, retroactively export existing sessions. ```bash # Convert every stored Codex CLI session specstory sync codex # Convert a single session by UUID specstory sync codex -s # Watch the sync progress specstory sync codex --console ``` - Session sources: Reads from `~/.codex/history`. The resulting Markdown files live under `.specstory/history/` with timestamps and metadata for easy sharing. ## Watch for Codex CLI activity Prefer to run the Codex CLI directly or via another tool? Use `specstory watch` to watch the current project directory for any new agent activity and auto-save it to markdown. ```bash # Watch for only activity from any supported coding agent specstory watch # Watch for only new Codex CLI agent activity specstory watch codex ``` Run `specstory watch` without an agent name to capture activity from any supported provider. ## Best Practices - **Segment workstreams**: Use Codex CLI’s commands to start fresh sessions per task so transcripts stay focused. - **Document custom tooling**: Add notes about bespoke scripts or workflows to the Markdown files for teammate handoff. - **Archive transcripts**: Commit `.specstory/history/` alongside your code to preserve design intent. ## Troubleshooting - `codex` command missing: Confirm installation by running `codex --version` outside SpecStory. - No Markdown output: Run inside a project directory that contains `.specstory/` and allows writing. - Sync returns nothing: Ensure Codex CLI has existing session logs in the current workspace. - Need assistance? Contact [support@specstory.com](mailto:support@specstory.com) or open a ticket on [GitHub](https://github.com/specstoryai/getspecstory/issues). --- ## Cursor CLI **URL:** https://docs.specstory.com/integrations/cursor-cli [Cursor CLI](https://docs.cursor.com/cli) mirrors the Cursor editor agent inside your terminal. Wrap it with SpecStory so the full discussion stays searchable and reviewable. ## Run Cursor CLI with SpecStory ```bash specstory run cursor ``` SpecStory stores transcripts, tool invocations, and shell output in `.specstory/history/`. You keep the normal Cursor CLI flow while gaining reviewable context. ## Sync existing Cursor CLI sessions Cursor CLI captures prior chats locally. Convert them into Markdown after the fact with `specstory sync`. ```bash # Export every Cursor CLI session specstory sync cursor # Only export one session (replace with its UUID) specstory sync cursor -s # Inspect sync logs in your terminal specstory sync cursor --console ``` - Session sources: Read from `~/.cursor/chats/` (local Cursor CLI session history). Each export creates a Markdown file named with the session timestamp. Share them in PRs or hand them to teammates as design history. ## Watch for Cursor CLI activity Prefer to run the Cursor CLI directly or via another tool? Use `specstory watch` to watch the current project directory for any new agent activity and auto-save it to markdown. ```bash # Watch for only activity from any supported coding agent specstory watch # Watch for only new Cursor CLI agent activity specstory watch cursor ``` Run `specstory watch` without an agent name to capture activity from any supported provider. ## Best Practices - **Scope conversations**: Use `/clear` or start fresh sessions per task to simplify review. - **Pair with Editor history**: Combine Cursor CLI transcripts with `.specstory/history/` from the editor UI for an end-to-end record. - **Include transcripts in reviews**: Point code reviewers at the relevant Markdown when opening a PR. ## Troubleshooting - `cursor-agent` not in `PATH`: Install the Cursor CLI and verify with `cursor-agent --help`. - No `.specstory/history/` files: Ensure you launched from inside a project folder with write permissions. - Sync returns zero sessions: Cursor CLI must have local session files in the working directory. - Still stuck? Email [support@specstory.com](mailto:support@specstory.com) or open an issue on [GitHub](https://github.com/specstoryai/getspecstory/issues). --- ## Cursor **URL:** https://docs.specstory.com/integrations/cursor SpecStory integrates seamlessly with [Cursor](https://cursor.com). Cursor already helps developers move faster with **inline edits**, **multi-line completions**, and **codebase chat**. SpecStory adds the missing layer by capturing *why* the changes were made. With SpecStory enabled, every AI conversation in Cursor is **auto-saved as Markdown** in your project. Your reasoning, tradeoffs, and design decisions live alongside your code: versioned, reusable, and shareable. ## Install the SpecStory Extension 1. Open **Cursor**. 2. Go to **Extensions Marketplace** (`Ctrl/Cmd+Shift+X`). 3. Search for **SpecStory** and click **Install**. 4. Verify installation: - Open the Command Palette (`Ctrl/Cmd+Shift+P`). - Type `SpecStory`, the commands should appear. ## Verify It Works - Start a chat with Cursor’s AI. - Open your project folder. - You should now see a new `.specstory/history/` directory. - Inside, you should see a Markdown file of your session, named with a timestamp. ## How SpecStory Enhances Cursor - **Auto-save:** Every AI conversations in Cursor are automatically stored in `.specstory/history/` as clean Markdown. - **Manual saves:** From the Command Palette, run `SpecStory: Save AI Chat History` to cherry-pick and combine conversations. - **Share conversations with a URL:** Use `SpecStory: Share AI Chat History` to generate a private, anonymous link at `share.specstory.com`. - **Derived rules for AI:** SpecStory can extract project-level rules and custom instructions from your chats, feeding them back into Cursor to improve suggestions. ## Best Practices for Cursor Users - **Commit your history**: Include `.specstory/history/` in your repo so teammates can review reasoning in PRs. - **Use manual saves before big changes**: Preserve the conversation context before accepting multi-line or agent-driven edits. - **Leverage derived rules**: Cursor’s [Project Rules](https://docs.cursor.com/context/rules-for-ai#project-rules-recommended) evolve automatically when SpecStory is active. ## Why This Matters Cursor accelerates *what* changes in your codebase. SpecStory ensures you never lose *why* those changes happened. Together, they give you: - Faster debugging and onboarding - Traceable architectural decisions - Cleaner collaboration on AI-assisted code ## Troubleshooting - **Extension mismatch**: If VS Code shows SpecStory installed but Cursor doesn’t, uninstall and reinstall from Cursor’s built-in Marketplace. - **No `.specstory` folder**: Make sure you have an active project folder open. SpecStory only saves inside projects. - **Still stuck**? File an issue on [GitHub](https://github.com/specstoryai/getspecstory/issues) or contact [support@specstory.com](mailto:support@specstory.com). --- ## Factory Droid **URL:** https://docs.specstory.com/integrations/droid-cli Factory [Droid](https://factory.ai/product/cli) is a model-agnostic, terminal-native autonomous AI coding agent. Capture your sessions with SpecStory and keep your prompts and reasoning intact as Markdown in your repo. ## Run Droid CLI with SpecStory ```bash specstory run droid ``` You can keep using Droid’s features like spec mode planning, skills, and slash commands like `/review`, etc. while SpecStory records the conversation and shell context. ## Sync existing Droid CLI sessions Forgot to launch with `specstory run`? Convert prior sessions with `specstory sync`. ```bash # Convert everything Droid CLI has stored locally specstory sync droid # Export a single session by ID specstory sync droid -s # Inspect sync logs in your terminal specstory sync droid --console ``` - Session sources: Reads from `~/.factory/` (Factory Droid agent's session storage). The resulting Markdown files live under `.specstory/history/` with timestamps and metadata for easy sharing. ## Watch for Droid CLI activity Prefer to run Droid CLI directly or via another tool? Use `specstory watch` to watch the current project directory for any new agent activity and auto-save it to markdown. ```bash # Watch for only activity from any supported coding agent specstory watch # Watch for only new Droid CLI activity specstory watch droid ``` Run `specstory watch` without an agent name to capture activity from any supported provider. ## Best Practices - Start a fresh session or clear context when you move from planning to implementation to review. - Add an `AGENTS.md` in your repo and ask Droid to read it before changes so SpecStory captures the shared context. - Use spec mode planning, then implement and finish with `/review` so the captured Markdown includes decisions and validation. - Use specialized skills for discrete tasks and keep their outputs in the transcript for review. - Document and archive Droid histories alongside code. ## Troubleshooting - `droid` command missing: Run `droid --version` outside SpecStory to verify installing Factory Droid CLI. - No Markdown output: Make sure you start `specstory run droid` inside a writable project folder. - `specstory sync` finds nothing: Droid CLI must have an existing session database in the current directory. - Need assistance? Contact [support@specstory.com](mailto:support@specstory.com) or open a ticket on [GitHub](https://github.com/specstoryai/getspecstory/issues). --- ## Gemini CLI **URL:** https://docs.specstory.com/integrations/gemini-cli [Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's terminal agent for code generation and multi-modal reasoning straight from the terminal. Pair it with SpecStory to turn every session into reusable Markdown notes. ## Run Gemini CLI with SpecStory ```bash specstory run gemini ``` You use Gemini CLI normally while SpecStory records the entire conversation and context. ## Sync older Gemini CLI sessions If you have used Gemini CLI before installing SpecStory, retroactively export existing sessions. ```bash # Convert every stored Gemini CLI session specstory sync gemini # Convert a single session by UUID specstory sync gemini -s # Inspect sync logs in your terminal specstory sync gemini --console ``` - Session sources: Read from `~/.gemini/tmp//chats`. The resulting Markdown files live under `.specstory/history/` with timestamps and metadata for easy sharing. ## Watch for Gemini CLI activity Prefer to run the Gemini CLI directly or via another tool? Use `specstory watch` to watch the current project directory for any new agent activity and auto-save it to markdown. ```bash # Watch for only activity from any supported coding agent specstory watch # Watch for only new Gemini CLI agent activity specstory watch gemini ``` Run `specstory watch` without an agent name to capture activity from any supported provider. ## Best Practices - **Segment workstreams**: Use Gemini CLI’s commands to start fresh sessions per task so transcripts stay focused. - **Document custom tooling**: Add notes about bespoke scripts or workflows to the Markdown files for teammate handoff. - **Archive transcripts**: Commit `.specstory/history/` alongside your code to preserve design intent. ## Troubleshooting - `gemini` command missing: Confirm installation by running `gemini --version` outside SpecStory. - No Markdown output: Run inside a project directory that contains `.specstory/` and allows writing. - Sync returns nothing: Ensure Gemini CLI has existing session logs in the current workspace. - Need assistance? Contact [support@specstory.com](mailto:support@specstory.com) or open a ticket on [GitHub](https://github.com/specstoryai/getspecstory/issues). --- ## VS Code + Copilot **URL:** https://docs.specstory.com/integrations/vscode SpecStory enhances **Visual Studio Code** with **GitHub Copilot** by preserving not just *what* was generated by AI, but *why* the changes were made. It automatically captures all AI chats as versioned Markdown in your project, deriving contextual instructions, and giving traceable reasoning behind your development choices. ## Install the SpecStory Extension 1. Open **VS Code** with **GitHub Copilot** enabled. 2. Go to **Extensions Marketplace** (`Ctrl/Cmd+Shift+X`) → search **SpecStory** → click **Install**. 3. To verify installation, open the Command Palette (`Ctrl/Cmd+Shift+P`) → type `SpecStory`. ## Verify It Works - Start an AI chat with GitHub Copilot in VS Code. - In your project, look for `.specstory/history/`. - You should see Markdown files representing your AI chat sessions, timestamped for clarity. ## Enhancing Copilot with Preserved Context - **Auto-save**: All Copilot conversations are captured automatically into `.specstory/history/`. - **Manual saves:** Run `SpecStory: Save AI Chat History` from the Command Palette to capture or combine selected sessions. - **Share sessions**: Use `SpecStory: Share AI Chat History` for to generate a private link sharing at `share.specstory.com`. - **Derived custom instructions**: SpecStory can generate project rules or [Copilot custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) directly from your conversations. These are stored as `copilot-instructions.md` under `.github/`. ## Advanced Workflow: Custom Instruction Files Copilot supports custom instruction files such as: - **`.github/copilot-instructions.md`** applies globally across the workspace. - **`*.instructions.md`** with `applyTo` frontmatter for scoped rules, such as specific file types. These improve consistency, e.g., enforcing coding conventions or architecture patterns. SpecStory can power these automatically, so your AI feels like part of your team's flow. ## Developer Best Practices for VS Code users - **Commit the history**: Version `.specstory/history/` so teammates can review decision and reasoning context in PRs. - **Manual save before big changes**: Capture the “why” before merging large Copilot completions or refactors. - **Leverage rules**: Derived rules ensure Copilot aligns with your team’s standards and conventions. 👉 Learn more: [GitHub Copilot Custom Instructions](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) ## Why This Matters GitHub Copilot accelerates *what* you type. SpecStory ensures you never lose *why* you typed it. Together, they enable: - Traceable architectural decisions - Faster onboarding and reviews for teammates - Reduced repetition in prompting - AI that understands your coding context naturally ## Troubleshooting - **SpecStory commands not showing:** If SpecStory doesn’t appear in VS Code, uninstall and reinstall from inside the VS Code Extensions Marketplace. - **No `.specstory` folder:** Make sure you have a workspace folder open, SpecStory only saves within projects. - **Copilot isn’t enabled:** Ensure [GitHub Copilot](https://github.com/features/copilot) is installed and active. - **Need help**? File an issue on [GitHub](https://github.com/specstoryai/getspecstory/issues) or email [support@specstory.com](mailto:support@specstory.com). --- ## Features **URL:** https://docs.specstory.com/specstory/features **Description:** Everything you can do with SpecStory ## Cursor and VS Code Extension ### Auto-save your AI conversations SpecStory automatically saves chat history in your project's `.specstory` folder. Each conversation is stored as a separate Markdown file so you retain the full context of every interaction. - Autosave is enabled by default but can be disabled with the `specstory.autoSave` setting. - Runs quietly in the background without interrupting your work. - Preserves the entire conversation, including code blocks and diffs. - Works in local workspaces as well as SSH, Dev Containers, and WSL. ### Manual save and export Need more control over what gets stored? Open the command palette (Cmd/Ctrl+Shift+P) and run `SpecStory: Save AI Chat History` to: - Select specific conversations to persist. - Combine multiple conversations into a single Markdown file. ### Share and annotate conversations Generate a secure public link by running `SpecStory: Share AI Chat History` from the command palette. - Receive a unique, shareable URL instantly—no account required. - Choose which conversations to include before publishing. - Edit the shared page with additional Markdown, images, or embedded videos. - Link a GitHub URL so reviewers can jump to the related work. - Cookie-based auth allows you to update or remove shares later. ### Derive rules for AI automatically Turn on automatic rule derivation with the `specstory.derivedRules` setting (available in SpecStory [v0.7.0](https://marketplace.visualstudio.com/items/SpecStory.specstory-vscode/changelog) and later). Key capabilities: - Generate `derived-rules.mdc` in `.cursor/rules` and `copilot-instructions.md` in `.github/`. - Back up previous versions in `.specstory/ai_rules_backups` and add the folder to `.gitignore` automatically. - Customize headers used in the generated rule files through settings. ### System prompt used for rule derivation ``` You are an expert software engineer responsible for maintaining a "living" and "evolving" AI coding assistant rules file. This file defines all project rules, coding standards, workflow guidelines, references, documentation structures, and best practices. Each time you receive new user–AI interactions, you must merge any relevant new guidelines, clarifications, or decisions into the file which is stored in the root of the project and is obeyed by the AI coding assistant. Rules for Updating: 1. Retain the structure of the AI coding assistant rules file, which uses the following top-level sections: 2. Read the new user–AI interactions carefully. Identify any instructions, new rules, clarifications, or best practices that arise. Incorporate them into the correct sections. If a new rule conflicts with an existing one, note the conflict and either: - Resolve it by clarifying the final, decided rule, - OR highlight that further user confirmation is needed. 3. Do not remove or discard existing content unless there is a clear directive to do so, but if a new rule supersedes or modifies old content, replace or annotate the old content accordingly. Don't let the rule file grow too much. 4. Maintain consistent markdown format, with ## headings for the top-level structure. 5. If version updates or references to version changes arise record them under the relevant section(s). For example, if it impacts the "TECH STACK" or "PROJECT DOCUMENTATION & CONTEXT SYSTEM", note it there. 6. If any mention of new coding tools or libraries arises, add them under the correct section (e.g., "TECH STACK") but do not remove previous entries. 7. If new debugging or workflow rules appear in the saved chat as a result of a user request to the AI, insert them into the correct sections (e.g., "DEBUGGING" or "WORKFLOW & RELEASE RULES"). 8. Look for signals that the user's intent is to make something a permanent rule. This includes words like "don't","must", "should", "always", "never", "all the time", "every time", "every time you see this", etc. 9. Don't make ANY adjustments to the AI coding assistant rules file unless you are absolutely sure that the user's intent is rule like in nature. Err on the side of making too few adjustments, not too many. It's perfectly fine to leave the file as it is. 10. After merging all relevant updates, output the entire updated AI coding assistant rules file as a single cohesive markdown document. Do not include extraneous commentary or placeholders, just the final updated file content. --- TASK: Please merge the new interactions into the AI coding assistant rules file as specified, and return the complete updated file content in markdown format. Ensure all headings remain in order, conflicts are addressed, and the file remains consistent and comprehensive. OUTPUT FORMAT: You must return the updated AI coding assistant rules file as a single cohesive markdown document. Do not include extraneous commentary. You must return the response inside a tag. Example: Content of the updated AI coding assistant rules file The MOST IMPORTANT THING is that you must return the response inside a tag. ``` --- ## Install our extensions **URL:** https://docs.specstory.com/specstory/introduction **Description:** Save, search and share your AI chat history with SpecStory. ## Multiplatform support is now here SpecStory saves, organizes, and makes all your AI chats searchable in structured Markdown. Never lose a great solution, easily share interactions, and use conversation history to refine Copilot and Cursor with custom instructions and project rules. ## Installation Options Choose your installation method based on your IDE: ### Extensions for VSCode & Cursor 1. Make sure you're on the latest version of [GitHub Copilot](https://github.blog/changelog/label/copilot/) or [Cursor](https://www.cursor.com/changelog). 2. Download our extension: [specstory-vscode-latest.vsix](https://static.specstory.com/vscode-extension/releases/specstory-vscode-latest.vsix) 3. From either editor, pop open the Command Palette (Ctrl/CMD-Shift-P) and choose `Extensions: Install from VSIX…`. 4. To verify the installation, open the Command Palette again (Ctrl/CMD-Shift-P) and type `SpecStory`. You should see the available commands show up. ### SpecStory CLI for Terminal Agents ## Why this will rock your world Think of [SpecStory](https://specstory.com) as your AI conversation time machine. - Auto-save your conversations into digestible Markdown format (readable by both humans AND machines). - Make your [vibe-coding](https://x.com/karpathy/status/1886192184808149383) adventures shareable via URLs at share.specstory.com. - Auto-magically derive Copilot [custom instructions](https://code.visualstudio.com/docs/copilot/copilot-customization) and Cursor [project rules](https://docs.cursor.com/context/rules-for-ai#project-rules-recommended) to improve agent-first coding performance. Your AI companion is about to get significantly less forgetful, and you won't have to lift a finger, so let's go! --- ## Quickstart **URL:** https://docs.specstory.com/specstory/quickstart **Description:** Give your AI assistant a persistent memory. ## Capture specific chats on demand Want to bundle selected conversations into a single file? Open the command palette (Cmd/Ctrl+Shift+P) and run `SpecStory: Save AI Chat History`. - Save curated conversations into one Markdown document. - The file opens immediately so you can review or edit before saving. - Commit the resulting Markdown alongside your code for a complete record. ## Publish a shareable link Share a conversation by running `SpecStory: Share AI Chat History` from the command palette. - Generate a private URL without creating an account. - Add descriptions, images, and additional Markdown sections before publishing. - Email [support@specstory.com](mailto:support@specstory.com) with the link if you ever need us to remove a shared conversation. ## Derive rules for AI automatically Not familiar with AI rules? - GitHub Copilot [custom instructions](https://code.visualstudio.com/docs/copilot/copilot-customization) - Cursor [project rules](https://docs.cursor.com/context/rules-for-ai#project-rules-recommended) or [Cursor101.com](https://cursor101.com/cursor/rules) SpecStory analyzes your conversations to capture: - The level of detail you typically request from AI responses. - Any rule or header structure you rely on when guiding the model. - How you iterate between suggestions and code edits. - Architectural patterns that repeatedly surface in your prompts. The extension then writes out editor-specific rules in the appropriate locations: 1. `.github/copilot-instructions.md` 2. `.cursor/rules/derived-rules.mdc` ### Prompt headers SpecStory relies on consistent headers to generate high-quality rules. We include a default template informed by community best practices. ### Benefits - Spend less time re-explaining preferences in every prompt. - Get faster, more aligned suggestions from Copilot and Cursor. - Let project rules evolve automatically as conversations provide new guidance. --- ## Settings **URL:** https://docs.specstory.com/specstory/settings **Description:** Change how SpecStory works. ## Extension Settings (Cursor and VS Code) Configure SpecStory in the editor via **Settings → User → Extensions → SpecStory**. - Enable or disable autosave. - Turn on Derived Rules and customize the headers used in rule files. - Opt out of product analytics. - Enable debug logging tools. ### Available Settings | Setting | Description | Default | | ------------------------ | ------------------------------------------- | -------------- | | `specstory.autoSave` | Enable automatic saving of AI conversations | `true` | | `specstory.derivedRules` | Enable automatic rule generation | `false` | | `specstory.fileHeaders` | Custom headers for rule generation | (see defaults) | | `specstory.analytics` | Enable anonymous usage analytics | `true` | | `specstory.debug` | Enable debug mode and verbose logging | `false` | ### Debugging tools - Browse, search, and copy the raw Workspace Storage and "Composer" Storage state in the left side (primary side bar) file explorer, in the VS CODE STATE panel. - View the **OUTPUT** panel and select the "SpecStory" channel from the dropdown to see debug logs. --- ## Delete Project **URL:** https://docs.specstory.com/api-reference/projects/delete-project **Description:** Permanently delete a project and all its sessions ## Request ## Response --- ## List Projects **URL:** https://docs.specstory.com/api-reference/projects/list-projects **Description:** Retrieve all projects in your workspace ## Request ## Response --- ## Update Project **URL:** https://docs.specstory.com/api-reference/projects/update-project **Description:** Update project name, icon, or color ## Request ## Response --- ## Check Session **URL:** https://docs.specstory.com/api-reference/sessions/check-session **Description:** Check if a session exists and get metadata without retrieving content ## Request ## Response This endpoint returns only HTTP status codes and headers, no response body. ### Response Headers | Header | Description | |--------|-------------| | `ETag` | Entity tag for the session version | | `Last-Modified` | Last modification timestamp | | `Content-Length` | Size of the session content | ### Status Codes | Status | Description | |--------|-------------| | `200` | Session exists | | `304` | Not Modified (if ETag matches) | | `401` | Unauthorized | | `404` | Session not found | --- ## Delete Session **URL:** https://docs.specstory.com/api-reference/sessions/delete-session **Description:** Permanently delete a session and its content ## Request ## Response --- ## Get Recent Sessions **URL:** https://docs.specstory.com/api-reference/sessions/get-recent-sessions **Description:** Retrieve the most recent sessions across all projects ## Request ## Response --- ## Get Session **URL:** https://docs.specstory.com/api-reference/sessions/get-session **Description:** Retrieve a specific session with its content and metadata ## Request ## Response --- ## List Sessions **URL:** https://docs.specstory.com/api-reference/sessions/list-sessions **Description:** List all sessions for a specific project ## Request ## Response --- ## Configuration **URL:** https://docs.specstory.com/integrations/terminal-coding-agents/configuration ## SpecStory CLI Configuration This page is a quick reference for SpecStory CLI commands, flags, and the files created in your repo. ### Commands | Command | Description | Examples | | :-------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | `version` | Display the current SpecStory version | `specstory version` | | `check` | Verify if terminal agents are installed and accessible to SpecStory | `specstory check` | | `run` | Launch an agent and auto-save sessions to Markdown (and Cloud if logged in) | `specstory run claude`
`specstory run cursor`
`specstory run codex`
`specstory run droid`
`specstory run gemini` | | `sync` | Convert past sessions to Markdown and optionally sync them to SpecStory Cloud | `specstory sync`
`specstory sync -s ` | | `watch` | Watch for new agent activity and auto-save to Markdown | `specstory watch`
`specstory watch cursor`
`specstory watch codex`
`specstory watch droid`
`specstory watch gemini` | | `login` | Authenticate with SpecStory Cloud | `specstory login` | | `logout` | Sign out of SpecStory Cloud | `specstory logout` | | `help` | Show help information | `specstory help`
`specstory help run` | ### Project scaffolding The first run inside a project creates: - `.specstory/` for state and configuration. - `.specstory/history/` for exported Markdown. - `.specstory/.project.json` for project bookkeeping. ```text / └── .specstory/ ├── history/ # Markdown session transcripts ├── debug/ # Debug logs (if --log enabled) │ └── debug.log └── .project.json # Project bookkeeping ``` ### Default behavior - Session storage: `.specstory/history/` in the working directory. - Cloud sync: Enabled when logged in with `specstory login` unless `--no-cloud-sync` is provided. - Session sources: Reads from `~/.claude/projects/`, `~/.cursor/chats/`, `~/.factory/`, `~/.codex/history`, and `~/.gemini/tmp//chats`. - Output format: Markdown files stamped with the session timestamp. - Timezones: Use `--local-time-zone` to stamp file names and content in local time. ### Flags | Flag | Description | Usage | | ---------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | `-c, --command` | Use a custom terminal-agent command or args | `specstory run claude -c "claude --dangerously-skip-permissions"` | | `-s, --session` | Convert a specific session to Markdown | `specstory sync claude -s ` | | `--console` | Stream log output to stdout | `specstory sync --console` | | `--log` | Write logs to `./specstory/debug/debug.log` | `specstory sync --log` | | `--debug` | Include debug-level output (requires `--console` or `--log`) | `specstory sync --log --debug` | | `--silent` | Suppress non-error output | `specstory sync --silent` | | `--local-time-zone` | Use local timezone for file name and content timestamps | `specstory sync --local-time-zone` | | `--no-cloud-sync` | Disable cloud sync even when authenticated | `specstory run --no-cloud-sync` | | `--only-cloud-sync` | Disable local markdown writing and only sync to cloud | `specstory watch --only-cloud-sync` | | `--no-usage-analytics` | Opt out of usage analytics | `specstory sync --no-usage-analytics` | | `--no-version-check` | Skip the version check | `specstory run codex --no-version-check` | | `--output-dir` | Write Markdown exports to a custom directory | `specstory watch --output-dir ~/my-agent-sessions` | | `-h, --help` | Show help information for a command | `specstory -h` | | `-v, --version` | Show the current SpecStory version | `specstory -v` | ### Debugging Use console streaming (`--console`) or log files (`--log`) to inspect details (`--debug`) on processing. ```bash # Run interactively with verbose output specstory run claude --console --debug # Capture logs without console noise specstory sync cursor --log # Capture detailed logs specstory watch --log --debug ``` Log output highlights: - `--log` output written to `./.specstory/debug/debug.log` - Which session files are being parsed. - Where Markdown exports are written. - Errors encountered during capture or sync. --- ## Overview **URL:** https://docs.specstory.com/integrations/terminal-coding-agents --- ## Links - [Main Site](https://specstory.com) - [Full Site LLMS.txt](https://specstory.com/llms-full.txt) - [GitHub](https://github.com/specstoryai) - [Discord](https://discord.gg/E47yQyEUd3) - [Slack](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg)