An agentic development framework. Track tickets, issues, and progress for your project in a .story/ directory that AI tools read and write natively.

claudestory.com | Documentation | Privacy Policy

Installation

npm install -g @anthropologies/claudestory

Requires Node.js 20+.

Quick Start

# Initialize in your project
claudestory init --name "my-project"

# See project state
claudestory status

# What should I work on next?
claudestory ticket next

# Check for data integrity issues
claudestory validate

CLI Commands

All commands support --format json|md (default: md).

Project

Command	Description
`claudestory init [--name] [--force]`	Scaffold `.story/` directory
`claudestory status`	Project summary with phase statuses
`claudestory validate`	Reference integrity + schema checks

Phases

Command	Description
`claudestory phase list`	All phases with derived status
`claudestory phase current`	First non-complete phase
`claudestory phase tickets --phase <id>`	Leaf tickets for a phase
`claudestory phase create --id --name --label --description [--summary] --after/--at-start`	Create phase
`claudestory phase rename <id> [--name] [--label] [--description] [--summary]`	Update phase metadata
`claudestory phase move <id> --after/--at-start`	Reorder phase
`claudestory phase delete <id> [--reassign <target>]`	Delete phase

Tickets

Command	Description
`claudestory ticket list [--status] [--phase] [--type]`	List leaf tickets
`claudestory ticket get <id>`	Ticket detail
`claudestory ticket next`	Highest-priority unblocked ticket
`claudestory ticket blocked`	All blocked tickets
`claudestory ticket create --title --type --phase [--description] [--blocked-by] [--parent-ticket]`	Create ticket
`claudestory ticket update <id> [--status] [--title] [--phase] [--order] ...`	Update ticket
`claudestory ticket delete <id> [--force]`	Delete ticket

Issues

Command	Description
`claudestory issue list [--status] [--severity]`	List issues
`claudestory issue get <id>`	Issue detail
`claudestory issue create --title --severity --impact [--components] [--related-tickets] [--location]`	Create issue
`claudestory issue update <id> [--status] [--title] [--severity] ...`	Update issue
`claudestory issue delete <id>`	Delete issue

Handovers

Command	Description
`claudestory handover list`	List handover filenames (newest first)
`claudestory handover latest`	Content of most recent handover
`claudestory handover get <filename>`	Content of specific handover

Blockers

Command	Description
`claudestory blocker list`	List all blockers with dates
`claudestory blocker add --name [--note]`	Add a blocker
`claudestory blocker clear <name> [--note]`	Clear an active blocker

MCP Server

The MCP server provides 19 tools for Claude Code integration. It imports the same TypeScript modules as the CLI directly — no subprocess spawning.

Setup with Claude Code

npm install -g @anthropologies/claudestory
claude mcp add claudestory -s user -- claudestory --mcp

Two commands: install globally, register as MCP server. Works in every project that has a .story/ directory. The MCP server auto-discovers the project root by walking up from the working directory.

MCP Tools

Tool	Description
`claudestory_status`	Project summary
`claudestory_phase_list`	All phases with status
`claudestory_phase_current`	Current phase
`claudestory_phase_tickets`	Tickets for a phase
`claudestory_ticket_list`	List tickets (filterable)
`claudestory_ticket_get`	Get ticket by ID
`claudestory_ticket_next`	Priority ticket
`claudestory_ticket_blocked`	Blocked tickets
`claudestory_issue_list`	List issues (filterable)
`claudestory_issue_get`	Get issue by ID
`claudestory_handover_list`	List handovers
`claudestory_handover_latest`	Latest handover
`claudestory_handover_get`	Specific handover
`claudestory_blocker_list`	List blockers
`claudestory_validate`	Integrity checks
`claudestory_recap`	Session diff + suggested actions
`claudestory_snapshot`	Save state for session diffs
`claudestory_export`	Self-contained project document

Session Lifecycle

Session Start (recommended hook)

Auto-inject project recap at session start — shows what changed since last snapshot and what to work on next:

#!/bin/bash
claudestory recap --format md 2>/dev/null

PreCompact Hook (auto-snapshot)

setup-skill configures a PreCompact hook that runs claudestory snapshot --quiet before context compaction. This ensures recap always shows changes since the last compaction — no manual snapshots needed.

Installed automatically by setup-skill. To skip: claudestory setup-skill --skip-hooks.

Manual configuration (add to ~/.claude/settings.json):

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claudestory snapshot --quiet"
          }
        ]
      }
    ]
  }
}

Session End

Save a snapshot before ending your session so the next recap can show diffs:

claudestory snapshot

Export

Generate a self-contained document for sharing:

claudestory export --phase p5b          # single phase
claudestory export --all                # entire project
claudestory export --all --format json  # structured JSON

Library Usage

import { loadProject, ProjectState } from "@anthropologies/claudestory";

const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length); // all tickets
console.log(state.phaseTickets("p1")); // tickets in phase p1