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.
SpecStory’s VSIX extension works with both VS Code and Cursor. If you use both, you’ll need to install separately in each editor.

​
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.
SpecStory is local-first: conversations are saved on your machine, never sent elsewhere unless you explicitly share.

​
Enhancing Copilot with Preserved Context

  • Auto-save: All Copilot conversations are captured automatically into .specstory/history/.
Autosave your 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.
Share your chat history
  • Derived custom instructions: SpecStory can generate project rules or Copilot custom instructions directly from your conversations. These are stored as copilot-instructions.md under .github/.
Rule derivation requires:
  • Auto-save turned on.
  • Signed-in SpecStory extension.

​
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

​
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 is installed and active.
  • Need help? File an issue on GitHub or email support@specstory.com.