SpecStory: local-first capture of AI coding sessions, with an optional cloud

The problem: AI conversations are the design record, and they evaporate

Most of the reasoning behind a change now happens inside a chat window. You ask Claude Code why a migration is failing, it proposes an approach, you push back, it revises. An hour later the working directory contains the result and nothing else. The prompt that produced the fix, the rejected alternative, the version constraint that ruled out the obvious library: all of it lives in a transcript that the tool may or may not keep, in a format you cannot grep.

SpecStory's answer is to treat those transcripts as project artifacts. Its README states the goal plainly: capture, index and make searchable every interaction with AI coding assistants across all projects and tools. The audience is individual developers and small teams who move between several agents in a week, and who have felt the specific pain of remembering that a problem was solved before without being able to find where. The repository covers eleven tools in its diagram, including Cursor IDE, Copilot IDE, Claude Code CLI, Cursor CLI, Codex CLI, Droid CLI, Gemini CLI, DeepSeek TUI, Antigravity CLI, Muse Code and Pi.

How capture works: extensions and a CLI writing into .specstory/history/

The mechanism is deliberately unglamorous. Each supported tool gets either an IDE extension or a CLI provider, and that component writes the conversation into a .specstory/history/ directory inside the project. The README's diagram shows the flow as AI coding tools on the left, local-first storage in the middle, and an optional cloud platform on the right marked login required. The repository layout matches that split: a specstory-cli/ directory holds the Go CLI, with a pkg/providers/ subtree containing one package per agent (the README links to pkg/providers/claudecode and pkg/providers/codexcli), while lore/ holds the skill-generation component and workthreads/ is a separate top-level directory.

Two consequences follow from putting history in the project directory. First, the transcript travels with the code: a clone includes it, and it can be reviewed like any other file. Second, it is a file you can accidentally commit, which is why the repository ships a .cursorindexingignore and a .gitignore at the root. The sync step is conditional, not automatic. According to the README, sessions reach cloud.specstory.com only if you are logged in. Everything before that point stays on disk.

The processing stage is where the project differs from a plain logger. The README describes running /lore to mine history into reusable, evidence-backed agent skills, and the Lore component is described as forging skills from how you actually work. That is the interesting claim: the output is not a transcript archive but a set of instructions derived from your own sessions. The README does not document how conflicts between mined skills are resolved, so treat the quality of that output as something to inspect on your own history rather than assume.

Installing the SpecStory CLI on macOS and capturing a first session

The README gives Homebrew as the installation path for the open-source CLI. Two commands, run in order, add the tap and install the binary.

brew tap specstoryai/tap
brew install specstory

After that, `specstory` should be on your PATH. The README does not print example CLI invocations beyond the install lines, so the first real use depends on which agent you run. For Claude Code, the table lists a minimum version of v1.0.27+; for Codex CLI it lists v0.42.0+. Install the CLI, then use your agent as usual in a project directory, and check for the history directory afterward. The README's diagram names .specstory/history/ as the location where sessions are auto-saved locally, so that directory is what to look for.

If the integration is working, that directory exists and contains your session. The IDE route is different and does not involve Homebrew: search for SpecStory in the extensions panel (Cmd/Ctrl+Shift+X) and install it, with a minimum of v0.43.6+ for Cursor and v1.300.0+ for VS Code with Copilot. The same marketplace listing, SpecStory.specstory-vscode, serves both. The README also mentions an install.sh at the repository root, but does not describe what it does, so the Homebrew path is the one with documented steps. Note that the CLI table is macOS-oriented; there is no documented Linux or Windows installation command in the README, even though a related search for a Mac build suggests that is where most people start.

Where SpecStory stops being the right tool

The local-first design has a cost that the README states without softening it: search across all projects and sharing with your team both run through the cloud platform, and the cloud platform requires a login. If your requirement is a shared, permissioned archive that a whole team can query, SpecStory's local directory is not that artifact. You would be adopting the cloud, and the open-source CLI is the capture half of a product whose retrieval half is hosted.

There is a second boundary. The repository is Go, the CLI is the open component, and the IDE extensions are marked Closed in the source column of the README's table. If your organisation requires every component that touches source code to be auditable, half of this stack fails that test before you evaluate anything else. The README also does not document rollback, retention limits or what a cloud deletion does to local files. Those are questions to put to the vendor, not gaps this article can fill.

A third constraint is version coupling. The table pins minimum versions per agent, and agents like Claude Code and Codex CLI ship frequently. An agent update that changes its on-disk session format is the obvious failure mode for a capture layer that reads those files, and the README does not describe a compatibility policy for it.

Alternatives: what changes if you keep transcripts in git instead

The closest alternative is not another product but a practice: commit the agent's own session files, or paste decisions into an ADR directory or a docs/decisions/ folder, and let git be the index. The difference is in who does the structuring. With SpecStory, a tool parses agent-specific formats and normalises them into .specstory/history/, and Lore then derives skills from the result, which means the heavy lifting is automated but the schema is the vendor's. With hand-written decision records, the format is yours and stable across agent changes, but nothing is captured unless you remember to write it, and you lose the raw transcript that shows how you got there.

A second alternative is the history feature built into the agent itself. Claude Code and Codex CLI both keep their own session state; SpecStory's value is that it reads those stores and writes a portable copy into the repository, so the record survives a tool switch. If you only ever use one agent and never leave it, that portability is worth less than it looks. The honest framing is that SpecStory is a bet that you will keep switching agents and keep wanting the old conversations.

Maintenance, licence and what the repository tells you about cost

The last push to the repository was on 2026-09-14, and v2.11.0 was released the same day, following v2.10.0 on 2026-08-17 and v2.9.0 on 2026-08-12. That is a fast release cadence, and it implies an upgrade cost: if you pin the CLI, expect to move versions often to stay compatible with agent releases. The repository is not archived. It ships a .goreleaser.yml, so release artifacts are produced by GoReleaser, and the default branch is dev rather than main, which means the stable line is a tag, not the branch tip. If you build from source, build from a release tag.

The licence situation needs care. The repository is Apache-2.0, and LICENSE.txt sits at the root. But the README's own table marks the Cursor and VS Code Copilot extensions as Closed source, and the open-source badge in the README points specifically at the CLI. So the Apache-2.0 grant covers the Go CLI and the lore/ and workthreads/ directories as they appear in the repository, not the marketplace extensions. That distinction matters for anyone doing licence review, and it is the kind of thing to confirm with the project rather than infer. Nothing here is legal advice.

Editorial conclusion

Adopt SpecStory if you already use Claude Code, Codex CLI, Cursor or Copilot and want a durable local record of the prompts and diffs behind your code, especially if you intend to reuse that record as agent skills through Lore. Skip it if your team needs a shared, searchable archive with per-user access control, because the README ties cross-project search and sharing to the cloud login, and the CLI is documented for macOS via Homebrew and for Claude Code and Codex CLI only. Before rolling it out, verify that your agent's version meets the stated minimums (v1.0.27+ for Claude Code, v0.42.0+ for Codex CLI, v0.43.6+ for the Cursor extension, v1.300.0+ for the Copilot extension), confirm that .specstory/history/ is what actually appears in a test repository, and read LICENSE.txt at the repository root rather than relying on the Apache-2.0 label.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. specstoryai/getspecstory on GitHub