sudocode stats

Syntax

sudocode stats

Description

The stats command provides detailed metrics and analytics about your sudocode project, including:

Entity counts: Total specs and issues
Issue breakdowns: Counts by status, ready/blocked analysis
Relationship metrics: Total relationships and counts by type
Recent activity: Updates, creations, and closures in the last 7 days

This command is perfect for:

Project health analysis
Understanding project structure
Tracking activity trends
Generating reports
Identifying patterns

For a quick overview, use status instead. Use stats when you need detailed metrics and analytics.

Examples

Basic Statistics

Get project statistics:

sudocode stats

Expected output

Project Statistics

Specs:
  Total: 12

Issues:
  Total: 47
  By Status: 15 open, 8 in_progress, 3 blocked, 5 needs_review, 16 closed
  Ready: 10
  Blocked: 3

Relationships:
  Total: 32
  5 blocks, 12 implements, 8 depends-on, 4 references, 3 related

Recent Activity (last 7 days):
  4 specs updated
  18 issues updated
  6 issues created
  5 issues closed

JSON Output

Get detailed machine-readable output:

sudocode --json stats

JSON output

{
  "specs": {
    "total": 12
  },
  "issues": {
    "total": 47,
    "by_status": {
      "open": 15,
      "in_progress": 8,
      "blocked": 3,
      "needs_review": 5,
      "closed": 16
    },
    "ready": 10,
    "blocked": 3
  },
  "relationships": {
    "total": 32,
    "by_type": {
      "blocks": 5,
      "implements": 12,
      "depends-on": 8,
      "references": 4,
      "related": 3
    }
  },
  "recent_activity": {
    "specs_updated": 4,
    "issues_updated": 18,
    "issues_created": 6,
    "issues_closed": 5
  }
}

Statistics Explained

Specs Section

Specs:
  Total: 12

Total - Number of specification documents in the project

Issues Section

Issues:
  Total: 47
  By Status: 15 open, 8 in_progress, 3 blocked, 5 needs_review, 16 closed
  Ready: 10
  Blocked: 3

Total - All issues across all statuses
By Status - Breakdown by each status:
- open - Not yet started
- in_progress - Currently being worked on
- blocked - Cannot proceed due to dependencies
- needs_review - Completed but awaiting review
- closed - Completed and accepted
Ready - Issues with no blockers, available to start
Blocked - Issues with active blocking dependencies

Relationships Section

Relationships:
  Total: 32
  5 blocks, 12 implements, 8 depends-on, 4 references, 3 related

Total - All typed relationships in the project
By type - Count for each relationship type:
- blocks - Blocking dependencies
- implements - Issue implements spec
- depends-on - Technical dependencies
- references - Cross-references
- related - General associations
- discovered-from - Feedback origin (if present)

Recent Activity Section

Recent Activity (last 7 days):
specs updated
issues updated
issues created
issues closed

specs_updated - Specs modified in last 7 days
issues_updated - Issues modified in last 7 days (any field)
issues_created - New issues created in last 7 days
issues_closed - Issues completed in last 7 days

Common Workflows

Monthly Project Review

Generate statistics

sudocode stats

Analyze metrics

Review:

Completion rate (closed vs total)
Bottlenecks (blocked count)
Activity trends (recent activity)
Relationship complexity (total relationships)

Generate report

Save to file:

sudocode stats > monthly-report-$(date +%Y-%m).txt

Project Health Dashboard

Create a comprehensive dashboard:

#!/bin/bash
clear
echo "╔══════════════════════════════════════════════╗"
echo "║        Project Analytics Dashboard          ║"
echo "╚══════════════════════════════════════════════╝"
echo ""

data=$(sudocode --json stats)

# Entity counts
specs=$(echo "$data" | jq '.specs.total')
issues=$(echo "$data" | jq '.issues.total')
rels=$(echo "$data" | jq '.relationships.total')

echo "📚 Entities"
echo "  Specs: $specs"
echo "  Issues: $issues"
echo "  Relationships: $rels"
echo ""

# Status breakdown
closed=$(echo "$data" | jq '.issues.by_status.closed')
total=$(echo "$data" | jq '.issues.total')
completion=$((closed * 100 / total))

echo "📊 Progress"
echo "  Completion: $completion% ($closed/$total)"
echo "  In Progress: $(echo "$data" | jq '.issues.by_status.in_progress')"
echo "  Needs Review: $(echo "$data" | jq '.issues.by_status.needs_review')"
echo ""

# Blockers
ready=$(echo "$data" | jq '.issues.ready')
blocked=$(echo "$data" | jq '.issues.blocked')

echo "🚦 Workflow"
echo "  Ready: $ready"
echo "  Blocked: $blocked"
if [ "$blocked" -gt 0 ]; then
  echo "  ⚠️  Attention needed on blockers"
fi
echo ""

# Activity
created=$(echo "$data" | jq '.recent_activity.issues_created')
closed_recent=$(echo "$data" | jq '.recent_activity.issues_closed')

echo "📈 Recent Activity (7 days)"
echo "  Created: $created"
echo "  Closed: $closed_recent"
echo "  Velocity: $(echo "scale=1; $closed_recent / 7" | bc) issues/day"

Compare Project Phases

Track metrics over time:

#!/bin/bash
# Save stats snapshots

timestamp=$(date +%Y-%m-%d)
sudocode --json stats > "stats-$timestamp.json"

echo "Stats saved to stats-$timestamp.json"

# Compare with last month
last_month=$(date -d '30 days ago' +%Y-%m-%d)
if [ -f "stats-$last_month.json" ]; then
  echo ""
  echo "Comparison with $last_month:"

  # Issues created
  current_total=$(jq '.issues.total' "stats-$timestamp.json")
  previous_total=$(jq '.issues.total' "stats-$last_month.json")
  new_issues=$((current_total - previous_total))
  echo "  New issues: $new_issues"

  # Issues closed
  current_closed=$(jq '.issues.by_status.closed' "stats-$timestamp.json")
  previous_closed=$(jq '.issues.by_status.closed' "stats-$last_month.json")
  closed_delta=$((current_closed - previous_closed))
  echo "  Issues closed: $closed_delta"
fi

Interpreting Metrics

Completion Rate

Calculate progress:

closed=$(sudocode --json stats | jq '.issues.by_status.closed')
total=$(sudocode --json stats | jq '.issues.total')
percentage=$((closed * 100 / total))
echo "Project completion: $percentage%"

Healthy range: 40-70% for active projects

<40%: Early phase or new issues being added rapidly
40-70%: Active development
>70%: Mature project or nearing completion

Bottleneck Indicator

Check blocked ratio:

blocked=$(sudocode --json stats | jq '.issues.blocked')
open=$(sudocode --json stats | jq '.issues.by_status.open')
in_progress=$(sudocode --json stats | jq '.issues.by_status.in_progress')
active=$((open + in_progress + blocked))

if [ "$active" -gt 0 ]; then
  block_ratio=$((blocked * 100 / active))
  echo "Blocked ratio: $block_ratio%"

  if [ "$block_ratio" -gt 20 ]; then
    echo "⚠️  High blocking - review dependencies"
  fi
fi

Healthy range: <20% blocked

<10%: Good flow
10-20%: Some dependencies, manageable
>20%: Excessive blocking, review dependencies

Activity Level

Assess project velocity:

closed_week=$(sudocode --json stats | jq '.recent_activity.issues_closed')
velocity=$(echo "scale=1; $closed_week / 7" | bc)
echo "Velocity: $velocity issues/day"

created_week=$(sudocode --json stats | jq '.recent_activity.issues_created')
burn_rate=$(echo "scale=1; ($closed_week - $created_week) / 7" | bc)
echo "Net burn rate: $burn_rate issues/day"

Interpretation:

Velocity: How fast work is completed
Burn rate: Net progress (closed - created)
- Positive: Reducing backlog
- Zero: Steady state
- Negative: Backlog growing

Relationship Density

Measure interconnectedness:

issues=$(sudocode --json stats | jq '.issues.total')
rels=$(sudocode --json stats | jq '.relationships.total')

if [ "$issues" -gt 0 ]; then
  density=$(echo "scale=2; $rels / $issues" | bc)
  echo "Relationship density: $density relationships/issue"
fi

Interpretation:

<1: Simple, loosely coupled
1-2: Moderate coupling, healthy
>2: High coupling, complex dependencies

Scripting Examples

Trend Analysis

Track metrics over time:

#!/bin/bash
# Append stats to time series log

date=$(date +%Y-%m-%d)
data=$(sudocode --json stats)

closed=$(echo "$data" | jq '.issues.by_status.closed')
total=$(echo "$data" | jq '.issues.total')
blocked=$(echo "$data" | jq '.issues.blocked')
ready=$(echo "$data" | jq '.issues.ready')

# Append to CSV
echo "$date,$total,$closed,$blocked,$ready" >> stats-history.csv
echo "Stats logged to stats-history.csv"

# Plot with gnuplot (if available)
if command -v gnuplot &> /dev/null; then
  gnuplot <<EOF
set terminal dumb
set title 'Issue Completion Trend'
set xlabel 'Date'
set ylabel 'Count'
set datafile separator ','
plot 'stats-history.csv' using 2 title 'Total' with lines, \
     '' using 3 title 'Closed' with lines
EOF
fi

Automated Alerts

Set up threshold alerts:

#!/bin/bash
# Alert on concerning metrics

data=$(sudocode --json stats)

# Too many blocked
blocked=$(echo "$data" | jq '.issues.blocked')
if [ "$blocked" -gt 10 ]; then
  echo "🚨 ALERT: $blocked blocked issues (threshold: 10)"
fi

# Low activity
closed_week=$(echo "$data" | jq '.recent_activity.issues_closed')
if [ "$closed_week" -lt 3 ]; then
  echo "⚠️  WARNING: Low activity - only $closed_week issues closed this week"
fi

# Completion stalled
needs_review=$(echo "$data" | jq '.issues.by_status.needs_review')
if [ "$needs_review" -gt 10 ]; then
  echo "⚠️  WARNING: $needs_review issues awaiting review"
fi

# Low ready work
ready=$(echo "$data" | jq '.issues.ready')
if [ "$ready" -lt 3 ]; then
  echo "⚠️  WARNING: Only $ready ready issues - may run out of work"
fi

Relationship Report

Analyze dependency patterns:

#!/bin/bash
echo "Relationship Analysis"
echo "===================="
echo ""

data=$(sudocode --json stats)

total=$(echo "$data" | jq '.relationships.total')
echo "Total relationships: $total"
echo ""

echo "By Type:"
for type in blocks implements depends-on references related discovered-from; do
  count=$(echo "$data" | jq ".relationships.by_type[\"$type\"] // 0")
  if [ "$count" -gt 0 ]; then
    percentage=$((count * 100 / total))
    printf "  %-15s: %3d (%2d%%)\n" "$type" "$count" "$percentage"
  fi
done

Common Questions

What's the difference between stats and status?

status: Quick overview, minimal info, focused on current state
stats: Detailed metrics, relationship counts, recent activity trends

Use status for daily checks, stats for analysis and reporting.

How is 'recent activity' calculated?

Recent activity looks at the last 7 days based on updated_at, created_at, and closed_at timestamps.

Why might relationship counts seem high?

Each relationship is counted once, but bidirectional relationships (like blocks) create two entries in the database. The count reflects total relationship records.

Can I customize the recent activity time window?

Not currently through the CLI. The 7-day window is hardcoded. For custom ranges, query the JSONL files directly or use the database.

Are archived issues included in counts?

No, archived issues and specs are excluded from all counts.

Can I export stats to a file?

Yes:

sudocode stats > stats-report.txt
# Or JSON
sudocode --json stats > stats.json

Troubleshooting

Stats show 0 for everything

Cause: No data in database or not in project directorySolution:

Verify you’re in project root
Check .sudocode/ directory exists
Run sync:
sudocode sync

Recent activity seems inaccurate

Cause: Timestamps may be from initial import, not actual activitySolution: Verify with:

sudocode --json issue list | jq '.[] | select(.updated_at > "2025-10-22") | .id'

Check specific issue timestamps.

Relationship counts don't match what I expect

Cause: May be counting both directions of bidirectional relationshipsSolution: Use --json output to inspect by_type breakdown and verify against your expectations.

Activity stats are zero but I've been working

Cause: Changes not committed to database or timestamps outdatedSolution:

sudocode sync
sudocode stats

status

Quick project overview

ready

Find ready work

blocked

Find blocked issues

issue list

List all issues

spec list

List all specs

Next Steps

Review statistics

sudocode stats

Identify concerns

Look for:

High blocked count
Low ready count
Stagnant activity
High relationship density

Take action

Based on findings:

Unblock issues
Create new work
Review dependencies
Adjust priorities

Track over time

Save stats snapshots:

sudocode --json stats > stats-$(date +%Y-%m-%d).json

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Syntax

Description

Examples

Basic Statistics

JSON Output

Statistics Explained

Specs Section

Issues Section

Relationships Section

Recent Activity Section

Common Workflows

Monthly Project Review

Project Health Dashboard

Compare Project Phases

Interpreting Metrics

Completion Rate

Bottleneck Indicator

Activity Level

Relationship Density

Scripting Examples

Trend Analysis

Automated Alerts

Relationship Report

Common Questions

Troubleshooting

status

ready

blocked

issue list

spec list

Next Steps

​Syntax

​Description

​Examples

​Basic Statistics

​JSON Output

​Statistics Explained

​Specs Section

​Issues Section

​Relationships Section

​Recent Activity Section

​Common Workflows

​Monthly Project Review

​Project Health Dashboard

​Compare Project Phases

​Interpreting Metrics

​Completion Rate

​Bottleneck Indicator

​Activity Level

​Relationship Density

​Scripting Examples

​Trend Analysis

​Automated Alerts

​Relationship Report

​Common Questions

​Troubleshooting

​Related Commands

status

ready

blocked

issue list

spec list

​Next Steps

Syntax

Description

Examples

Basic Statistics

JSON Output

Statistics Explained

Specs Section

Issues Section

Relationships Section

Recent Activity Section

Common Workflows

Monthly Project Review

Project Health Dashboard

Compare Project Phases

Interpreting Metrics

Completion Rate

Bottleneck Indicator

Activity Level

Relationship Density

Scripting Examples

Trend Analysis

Automated Alerts

Relationship Report

Common Questions

Troubleshooting

Related Commands

Next Steps