> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode stats

> View detailed project statistics and metrics

## Syntax

```bash theme={null}
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

<Note>
  For a quick overview, use `status` instead. Use `stats` when you need detailed metrics and analytics.
</Note>

## Examples

### Basic Statistics

Get project statistics:

```bash theme={null}
sudocode stats
```

<Accordion title="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
  ```
</Accordion>

### JSON Output

Get detailed machine-readable output:

```bash theme={null}
sudocode --json stats
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "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
    }
  }
  ```
</Accordion>

## 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):
  4 specs updated
  18 issues updated
  6 issues created
  5 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

<Steps>
  <Step title="Generate statistics">
    ```bash theme={null}
    sudocode stats
    ```
  </Step>

  <Step title="Analyze metrics">
    Review:

    * Completion rate (closed vs total)
    * Bottlenecks (blocked count)
    * Activity trends (recent activity)
    * Relationship complexity (total relationships)
  </Step>

  <Step title="Generate report">
    Save to file:

    ```bash theme={null}
    sudocode stats > monthly-report-$(date +%Y-%m).txt
    ```
  </Step>
</Steps>

### Project Health Dashboard

Create a comprehensive dashboard:

```bash theme={null}
#!/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:

```bash theme={null}
#!/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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
#!/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:

```bash theme={null}
#!/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:

```bash theme={null}
#!/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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="How is 'recent activity' calculated?">
    Recent activity looks at the last 7 days based on `updated_at`, `created_at`, and `closed_at` timestamps.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Are archived issues included in counts?">
    No, archived issues and specs are excluded from all counts.
  </Accordion>

  <Accordion title="Can I export stats to a file?">
    Yes:

    ```bash theme={null}
    sudocode stats > stats-report.txt
    # Or JSON
    sudocode --json stats > stats.json
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Stats show 0 for everything">
    **Cause:** No data in database or not in project directory

    **Solution:**

    1. Verify you're in project root
    2. Check `.sudocode/` directory exists
    3. Run sync:
       ```bash theme={null}
       sudocode sync
       ```
  </Accordion>

  <Accordion title="Recent activity seems inaccurate">
    **Cause:** Timestamps may be from initial import, not actual activity

    **Solution:**
    Verify with:

    ```bash theme={null}
    sudocode --json issue list | jq '.[] | select(.updated_at > "2025-10-22") | .id'
    ```

    Check specific issue timestamps.
  </Accordion>

  <Accordion title="Relationship counts don't match what I expect">
    **Cause:** May be counting both directions of bidirectional relationships

    **Solution:**
    Use `--json` output to inspect `by_type` breakdown and verify against your expectations.
  </Accordion>

  <Accordion title="Activity stats are zero but I've been working">
    **Cause:** Changes not committed to database or timestamps outdated

    **Solution:**

    ```bash theme={null}
    sudocode sync
    sudocode stats
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="status" icon="chart-simple" href="/cli/status">
    Quick project overview
  </Card>

  <Card title="ready" icon="circle-check" href="/cli/ready">
    Find ready work
  </Card>

  <Card title="blocked" icon="ban" href="/cli/blocked">
    Find blocked issues
  </Card>

  <Card title="issue list" icon="list" href="/cli/issue-list">
    List all issues
  </Card>

  <Card title="spec list" icon="file-lines" href="/cli/spec-list">
    List all specs
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Review statistics">
    ```bash theme={null}
    sudocode stats
    ```
  </Step>

  <Step title="Identify concerns">
    Look for:

    * High blocked count
    * Low ready count
    * Stagnant activity
    * High relationship density
  </Step>

  <Step title="Take action">
    Based on findings:

    * Unblock issues
    * Create new work
    * Review dependencies
    * Adjust priorities
  </Step>

  <Step title="Track over time">
    Save stats snapshots:

    ```bash theme={null}
    sudocode --json stats > stats-$(date +%Y-%m-%d).json
    ```
  </Step>
</Steps>