specstoryai/getspecstory: Index and Search AI Coding Conversations Locally

specstoryai/getspecstory: Index and Search AI Coding Conversations Locally

AI coding assistants have become indispensable for developers, but they come with a persistent problem: every brilliant solution, architectural decision, and debugging breakthrough disappears the moment you close the chat. specstoryai/getspecstory addresses this by capturing, indexing, and making searchable every interaction you have with AI coding assistants across all your projects and tools.

What is specstoryai/getspecstory?

specstoryai/getspecstory is an open-source tool (Apache License 2.0) primarily written in Go that provides local-first storage and indexing for AI coding conversations. With 1,279 GitHub stars and 80 forks, it has gained meaningful traction among developers who need to preserve their AI-assisted development workflows.

The project is maintained by SpecStory AI and operates on a "local-first, cloud-optional" architecture. All conversations are automatically saved to .specstory/history/ in your project directory. Nothing leaves your machine unless you explicitly create an account and opt into cloud synchronization.

The tool supports a broad ecosystem of AI coding assistants: Cursor IDE, GitHub Copilot (VSCode extension), Claude Code CLI, Cursor CLI, Codex CLI, Droid CLI, Gemini CLI, and DeepSeek TUI. This coverage reflects the fragmented reality of modern AI-assisted development—developers rarely use just one tool, and specstoryai/getspecstory meets them where they already work.

A distinguishing feature is Lore, a skill-forging system that mines your saved sessions into evidence-backed agent skills. Rather than hand-writing prompts that describe how you think you work, Lore analyzes what you actually ran, what worked, and the judgment you applied—then generates reusable skills for any Agent Skills-compatible agent.

The project also offers SpecStory Cloud, a centralized knowledge base with full-text search across projects, optional team features, and API access for automation. Cloud sync requires explicit login; the default behavior keeps everything local.

Key Features

Universal CLI and IDE Coverage: specstoryai/getspecstory integrates with eight distinct AI coding tools through two mechanisms. IDE extensions (closed source) handle Cursor and VSCode Copilot. The open-source CLI wraps Claude Code, Cursor CLI, Codex CLI, Droid CLI, Gemini CLI, and DeepSeek TUI. One brew install covers all CLI tools.

Local-First Data Architecture: Every session saves automatically to .specstory/history/ in your current project. This design choice prioritizes privacy and offline functionality. You retain complete control over your data; cloud synchronization is strictly opt-in after account creation.

Lore Skill Generation: The /lore command transforms historical sessions into structured, evidence-backed agent skills. These skills capture not just what commands you ran, but what succeeded, what failed, and the implicit patterns in your decision-making. Skills install via npx skills add specstoryai/getspecstory --skill lore and invoke with /lore in Claude Code, $lore in Codex, or natural language in other agents.

Cross-Project Search: The cloud platform (when enabled) provides full-text search across all synchronized projects, with RAG capabilities noted as coming soon. Local search operates within individual project histories.

Open-Source CLI Core: The CLI implementation is fully open source, with provider-specific code visible in the repository for Claude Code, Codex CLI, Cursor CLI, Droid CLI, Gemini CLI, and DeepSeek TUI integrations.

Use Cases

Recovering Lost Solutions: You spent twenty minutes debugging an edge case with Claude Code last month. The fix worked, but you didn't document it. With specstoryai/getspecstory, that conversation exists in .specstory/history/ and is text-searchable. No more re-deriving solutions from scratch.

Onboarding Team Members: New developers on your team encounter the same architectural questions repeatedly. Your project's .specstory/history/ contains the evolution of key decisions. Share relevant sessions—or sync to cloud for centralized access—rather than re-explaining context in Slack threads.

Building Evidence-Based Agent Skills: Hand-written .cursorrules or Copilot instructions often drift from actual practice. Lore analyzes your real sessions to generate skills grounded in demonstrated behavior. A team that consistently uses specific testing patterns or deployment checks gets skills that reflect those patterns, not idealized versions.

Compliance and Auditing: Organizations needing visibility into AI-assisted development can use local history files as an audit trail. The explicit opt-in cloud sync model also satisfies data governance requirements that prohibit automatic external transmission.

Cross-Tool Workflow Continuity: You prototype with Cursor IDE, refine with Claude Code CLI, and review with Copilot. specstoryai/getspecstory normalizes these disparate conversations into a single searchable format, preventing tool silos from fragmenting your development knowledge.

Installation & Setup

CLI Installation (All Terminal Agents)

# Add the SpecStory tap
brew tap specstoryai/tap

# Install the CLI
brew install specstory

This single installation enables session capture for Claude Code, Cursor CLI, Codex CLI, Droid CLI, Gemini CLI, and DeepSeek TUI.

IDE Extensions

Cursor: Open the Extensions panel (Cmd/Ctrl+Shift+X), search "SpecStory", and install directly within Cursor. Do not install from the Visual Studio Marketplace website—Cursor's extension ecosystem requires in-app installation.

VSCode with Copilot: Same process: Extensions panel → search "SpecStory" → install.

Lore Installation

npx skills add specstoryai/getspecstory --skill lore

Requires Node.js 22.5 or later.

Cloud Sync Setup (Optional)

CLI: specstory login

Cursor/VSCode Extensions: Command Palette → "SpecStory: Open Cloud Sync Configuration"

After login, configure auto-sync in settings or use manual sync commands for past sessions.

Real Code Examples

The specstoryai/getspecstory README provides explicit workflow commands. Below are the documented examples with explanation.

Checking Installed Agents

# Verify which AI agents are available on your system
specstory check

This command inspects your environment for supported CLI tools, confirming that subsequent specstory run commands will function correctly.

Launching Agents with Auto-Save

# Launch specific agents through the SpecStory wrapper
specstory run claude    # Launch Claude Code
specstory run cursor    # Launch Cursor CLI
specstory run codex     # Launch Codex CLI
specstory run droid     # Launch Droid CLI
specstory run gemini    # Launch Gemini CLI
specstory run deepseek  # Launch DeepSeek TUI
specstory run           # Launch default agent

Each invocation wraps the native agent, intercepting conversation data and persisting it to .specstory/history/ without modifying the underlying tool's behavior.

Syncing Historical Sessions

# Push existing local sessions to cloud (requires login)
specstory sync

Useful when you've accumulated local history before enabling cloud sync, or when working offline and reconnecting.

Invoking Lore

# In Claude Code
/lore

# In Codex CLI
$lore

# In Gemini CLI and others
# Natural language: "mine my lore"

Lore processes your .specstory/history directory and generates installable skills with attached evidence. You review and approve before deployment to your agents.

The README currently contains these four primary code examples. The tool's functionality is largely transparent—install, run your existing agents through the wrapper, and search the generated history files.

Advanced Usage & Best Practices

History File Management: The .specstory/history/ directory accumulates files over time. Consider adding this path to .gitignore to prevent committing potentially sensitive conversation data, while ensuring team members who need access use the cloud sync or shared storage mechanism instead.

Selective Cloud Sync: Even after logging in, you control what synchronizes. For projects with strict data requirements, omit specstory login or disable auto-sync in extension settings. The local-first design means functionality degrades gracefully to single-project, offline operation.

Lore Approval Workflow: Generated skills from Lore benefit from human review. The evidence attachment shows exactly which sessions contributed to each skill, enabling you to verify that representative successes—and not outliers—shaped the output.

Multi-Machine Setup: Developers working across multiple machines can use cloud sync as a convergence point, or manually merge .specstory/history/ directories. The plain-text history format facilitates both approaches.

Comparison with Alternatives

specstoryai/getspecstory's primary distinction is unified coverage across vendors with local-first storage. Cursor and Copilot native histories remain siloed to their respective platforms. Manual logging requires discipline most developers lack. The trade-off: specstoryai/getspecstory adds a dependency layer, and IDE extensions are closed source despite the open CLI core.

FAQ

Does specstoryai/getspecstory modify my AI agent's behavior? No. The CLI acts as a transparent wrapper. The native agent runs unchanged; conversation data is captured and saved separately.

What data leaves my machine? Nothing, unless you explicitly log into SpecStory Cloud and enable sync. Local save operates entirely offline.

Can I use this with self-hosted or enterprise AI tools? The README documents support for the eight named tools. Extending to other tools would require modifying the open-source CLI provider code.

Is the IDE extension source available? No. The Cursor and VSCode extensions are closed source. The CLI and Lore components are open source under Apache 2.0.

What license covers the open-source components? Apache License 2.0, as indicated in the repository metadata.

How recent is active development? The last commit was July 15, 2026, suggesting ongoing maintenance at the time of documentation.

Does Lore require cloud access? No. Lore operates on local .specstory/history files. Generated skills install to local agents.

Conclusion

specstoryai/getspecstory solves a concrete problem that intensifies as AI coding tools proliferate: the ephemeral nature of AI-assisted development knowledge. Its local-first architecture respects developer privacy while the optional cloud layer enables team scaling. The open-source CLI core provides transparency for the terminal agent integrations, and Lore offers a genuinely differentiated approach to skill generation based on demonstrated rather than assumed behavior.

This tool best serves developers who work across multiple AI coding assistants, teams needing to preserve and transfer development context, and organizations with data governance requirements that prohibit automatic cloud transmission. The 1,279-star repository reflects genuine interest, though users should note that IDE extensions remain closed source.

Ready to stop losing your best AI conversations? Explore the repository at https://github.com/specstoryai/getspecstory and install the CLI or IDE extension for your workflow.

For related approaches to development workflow preservation, see our coverage of [INTERNAL_LINK: local-first developer tools].