claudestory

claudestory.com | npm | Privacy Policy

Cross-session context persistence for AI coding assistants.

Every AI coding session starts from zero. The assistant doesn't know what was built yesterday, what's broken, what decisions were made, or what to work on next. Developers compensate with long startup prompts and scattered notes, but nothing carries forward automatically.

claudestory fixes this. A .story/ directory in your project tracks tickets, issues, roadmap, handovers, and notes. Structured data that AI assistants read and write natively. Session 47 builds on session 46 instead of starting over.

Quick Start

1. Install

npm install -g @anthropologies/claudestory

2. Set up the Claude Code skill and MCP server

claudestory setup-skill

3. Restart Claude Code, then type:

/story

On new projects, /story will analyze your codebase and offer to set up .story/ with phases, tickets, and issues -- no manual init needed.

Alternative: Install as Claude Code plugin

/plugin install story@claude-plugins-official

When installed as a plugin, the skill is available as /story:go.

What It Creates

your-project/
└── .story/
    ├── config.json        # Project metadata
    ├── roadmap.json       # Phases with status derived from tickets
    ├── tickets/           # One JSON file per work item (T-001.json, T-002.json, ...)
    ├── issues/            # One JSON file per bug/gap (ISS-001.json, ISS-002.json, ...)
    ├── notes/             # Brainstorming and ideas (N-001.json, N-002.json, ...)
    ├── lessons/           # Process knowledge that persists across sessions (L-001.json, ...)
    ├── handovers/         # Session continuity documents (markdown)
    └── snapshots/         # State snapshots for session diffs

Tickets are planned work — features, tasks, refactors. Issues are discovered problems — bugs, inconsistencies, gaps. Notes are unstructured brainstorming — ideas, design thinking, explorations. Lessons are structured process knowledge — patterns learned from reviews, mistakes, and decisions. Handovers capture what each session accomplished so the next one picks up seamlessly.

How It Works

Session start          Work                    Session end
     │                   │                          │
     ▼                   ▼                          ▼
  /story             tickets,              /story handover
  loads context      issues, notes          captures state
  from .story/       updated as             for next session
                     you work

1. Start — /story loads project status, latest handover, and development rules. You know exactly where things stand.
2. Work — Create tickets, log issues, update progress. The AI reads and writes .story/ files as part of normal development.
3. End — A handover document captures what was done, decisions made, and what's next. Snapshots enable session diffs.
4. Next session — /story loads the handover. The new session has full context from the previous one. No re-explanation needed.

Features

Session Management

• 30 MCP tools — Read and write project state from any MCP-compatible AI assistant
• Full CLI — claudestory status, ticket next, recommend, snapshot, recap, export, validate, and more
• /story skill — One-command session start for Claude Code
• Snapshots + Recaps — See what changed between sessions, with content diff tracking
• PreCompact hooks — Auto-snapshot before context compaction

Project Tracking

• Recommend engine — Context-aware work suggestions mixing tickets and issues, with phase-proximity and unblock-impact awareness
• Notes — Unstructured brainstorming with tags, archiving, and search
• Lessons — Structured process knowledge that persists and ranks across sessions by reinforcement count
• Export — Self-contained project documents for sharing
• Validation — Reference integrity checks across all .story/ files

Autonomous Mode

• /story auto — Picks tickets, plans, reviews, implements, and commits in a loop until all work is done
• Targeted auto — /story auto T-183 T-184 ISS-077 works only on specified items in order, then stops
• Multi-lens code review — 8 specialized reviewers run in parallel (clean code, security, error handling, performance, API design, concurrency, test quality, accessibility), findings synthesized into a single verdict. Runs automatically in autonomous mode or manually via /story review-lenses
• Multi-backend review — Independent plan and code review via pluggable backends (Codex, agent) with adaptive depth
• Frontend design evaluation — /story design evaluates UI against platform best practices (web, iOS, macOS, Android) with priority ordering: clarity > hierarchy > platform correctness > accessibility > state completeness
• TDD stage — Write tests before implementation, validate against baseline (configurable)
• Endpoint verification — Smoke test HTTP endpoints after code review (configurable)
• Periodic checkpoints — Auto-handover every N tickets for session continuity
• Tiered access — /story review T-XXX, /story plan T-XXX, /story guided T-XXX for scoped workflows
• Configurable pipeline — /story settings to tune quality stages, review backends, session limits, and handover frequency

Universal

• Language-agnostic — Works with any project, any language, any AI assistant that supports MCP

CLI + MCP Reference

See skills/go/reference.md for the full list of CLI commands and MCP tools.

The skill files in this repo are for reference. Authoritative versions are installed via claudestory setup-skill.

Install

npm install -g @anthropologies/claudestory

View on npm

---

© 2026 Amir Shayegh. Free for personal and noncommercial use under the PolyForm Noncommercial License 1.0. For commercial licensing, contact shayegh@me.com.