Specstory Project Stats

SpecStory Project Stats

Fetches project statistics from SpecStory's cloud platform, showing contributor counts, session activity, and other project metrics.

How It Works

1. Identifies the project via .specstory/.project.json, git remote, or folder name
2. Calls the SpecStory Cloud API
3. Returns project statistics in JSON format
4. Presents the data in a readable summary

Prerequisites

• Project must be synced to SpecStory Cloud
• Node.js must be available to run the script

Usage

Slash Command

| User says | Action | |-----------|--------| | /specstory-project-stats | Fetch stats for current project | | /specstory-project-stats | Same as above (no arguments needed) |

Direct Script Usage

# Fetch stats for current project
node skills/specstory-project-stats/scripts/get-stats.js

# With custom API endpoint (for development)
SPECSTORY_API_URL=http://localhost:5173 node skills/specstory-project-stats/scripts/get-stats.js

Output

The script outputs JSON with project statistics:

{
  "project_id": "specstoryai/agent-skills",
  "sessions": {
    "total": 156,
    "last_30_days": 47,
    "last_7_days": 12
  },
  "contributors": {
    "total": 5,
    "active_last_30_days": 3
  },
  "activity": {
    "first_session": "2025-10-15",
    "last_session": "2026-01-28",
    "avg_sessions_per_week": 8.2
  }
}

Project ID Resolution

The script determines project ID in this order:

1. .specstory/.project.json - Uses git_id or workspace_id field
2. Git remote - Extracts repo name from origin remote URL
3. Folder name - Falls back to current directory name

Error Handling

| Error | Meaning | Action | |-------|---------|--------| | 404 | Project not found | Project needs to sync to SpecStory Cloud first | | 401 | Unauthorized | API endpoint may require authentication | | Network error | Can't reach API | Check internet connection |

Present Results to User

After fetching stats, present them in a friendly format:

Example Response (success)

Here are the stats for **specstoryai/agent-skills**:

**Sessions**
- Total: 156 sessions captured
- Last 30 days: 47 sessions
- Last 7 days: 12 sessions

**Contributors**
- Total: 5 contributors
- Active recently: 3

**Activity**
- First session: October 15, 2025
- Most recent: January 28, 2026
- Average: ~8 sessions per week

Your project has been actively using AI-assisted coding!

Example Response (404 error)

This project doesn't exist on SpecStory Cloud yet.

To get started:
1. Make sure you have SpecStory installed
2. Run `specstory sync` to push your local sessions to the cloud
3. Try this command again

Need help? Check the docs at https://docs.specstory.com

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SPECSTORY_API_URL | https://cloud.specstory.com | API endpoint |

Notes

• Statistics are fetched from SpecStory Cloud, not local history
• Project must have synced sessions to show meaningful stats
• The API is public and doesn't require authentication for basic stats

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: specstoryai
• Source: specstoryai/agent-skills
• License: Apache-2.0
• Homepage: https://specstory.com/agent-skills

Install and usage instructions live in the source repository linked above.