Quickstart

​

🪄 Your work saves itself, no cloud required!

When you install SpecStory it begins its work in the background, automatically saving 🗄️ your AI chat history for your active project in ./specstory/history.

You can toggle this on and off in our settings.

​

🎯 Cherry pick your save worthy moments

If you want to combine selected conversations into a single file, you can do that too. Just open the command palette (Cmd/Ctrl+Shift+P) and run SpecStory: Save AI Chat History.

• 📝 Presto! Run this command and watch your AI conversations transform into a beautiful markdown file right before your eyes!
• 👀 No waiting around - it pops open instantly in your editor. (We love instant gratification!)
• 💾 Like what you see? Hit that Save button and your AI wisdom is safely tucked into your project files.
• 🌳 Feeling git-ty? Commit it to your repo just like any other file - because your AI conversations deserve version control too!

​

🌟 Share your history with a story!

Share your chat history with others by opening the command pallette and running SpecStory: Share AI Chat History.

• 🌎 Ready to share your AI coding adventures with the world? One command sends your chat history sailing into the cloud, returning a magical URL just for you!
• 🎭 No signup required - your shares are anonymous. (But hey, keep those secret API keys and passwords to yourself, okay?)
• 🔗 Pro tip: Bookmark that special URL like it’s your favorite cat gif - you’ll want it later!
• ✏️ As the creator, you can add a description to your share, paste images, and curate which chats to include.
• 📝 Mark it down: You can add tons of details to your share by adding sections of markdown-formatted text in between any parts of the conversation.
• 🗑️ Having second thoughts? Need to make something disappear? Drop us a line at support@specstory.com with a link to the share and we’ll take care of it faster than you can say “delete my search history.”

​

🧪 Auto-magically derive Rules for AI

• ❓ Unfamiliar with what rules for AI are? Consult their respective docs:
  • Copilot custom instructions
  • Cursor project rules or Cursor101.com.

There isn’t a palette command for this one. When you chat with AI, SpecStory is like a mystical scribe in the corner, quill poised, noting patterns in:

• 🧠 Your thinking style: Do you prefer step-by-step explanations or quick solutions?
• 🖋️ Your rule file headers: Those special incantations you set the structure of your derived file with.
• 🔄 Your iteration cycles: How you refine code and conversation together with AI.
• 🏗️ Your project structure: The architecture of your digital temple.

Then—abracadabra!—SpecStory transmutes these observations into editor specific rules for AI. Stored in either:

1. the .github/ directory as copilot-instructions.md
2. the .cursor/rules directory as derived-rules.mdc.

🌈 Prompt Headers: The Secret Ingredient

SpecStory needs your rule file headers to brew the perfect rules. To start you off, we’ve crafted a default based on distilled knowledge from the community of what tends to work best.

🌟 The Benefits of this Sorcery

• 🧙‍♀️ Less repetitive incantations: Reduced need to constantly explain your preferences every time.
• ⚡ Faster spell-casting: AI responses align with your project from the start.
• 🔄 Self-improving magic: As you work, the rules evolve to match your growing expertise.

​

🪄 Your work saves itself, no cloud required!

When you run Claude Code through SpecStory, it automatically saves your conversations in .specstory/history/ in your current project directory. The CLI acts as a wrapper, launching Claude Code while capturing all your chat sessions.

​

🎯 Save and organize your conversations

SpecStory provides simple flags to manage your Claude Code conversations:

# Run Claude Code through SpecStory wrapper (default)
specstory

# Sync all Claude Code sessions to markdown files
specstory -s

# Generate markdown for a specific session
specstory -u <session-uuid>

# Run with verbose output to see what's happening
specstory -s --verbose

• 📝 Automatic capture: Running specstory launches Claude Code and captures conversations
• 🗂️ Project-based organization: Sessions are saved in .specstory/history/ with timestamps
• 💾 Batch conversion: Use -s flag to convert all existing sessions to markdown
• 🌳 Git-friendly: All output is clean markdown, perfect for version control

​

🌟 Share your history with a story!

Currently, the SpecStory CLI wrapper focuses on capturing and converting your Claude Code sessions to markdown. Sharing features are on the roadmap!

For now, you can:

• Generate markdown files with specstory -s
• Find your conversations in .specstory/history/
• Share the markdown files directly or through your preferred method
• Commit them to git for team collaboration

​

🧪 Auto-magically derive Rules for AI

While the CLI doesn’t generate rules directly, your captured markdown sessions can be:

• Analyzed manually to identify patterns
• Used as context when crafting your own rules in (claude.md)
• Shared with team members to establish coding conventions