> ## 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 status

> Get a quick project status overview

## Syntax

```bash theme={null}
sudocode status [options]
```

## Description

The `status` command provides a high-level snapshot of your sudocode project, including:

* Total number of specs
* Issue counts by status (open, in\_progress, blocked, needs\_review, closed)
* Number of issues ready to work on
* Number of blocked issues
* Sync status

This command is perfect for:

* Daily standup meetings
* Quick project health checks
* Understanding current workload
* Monitoring project progress

<Note>
  Use `status` for a quick overview. For detailed statistics and metrics, use `stats` instead.
</Note>

## Options

<ParamField path="--verbose" type="boolean">
  Show detailed output (not currently implemented)

  **Example:** `--verbose`

  Future enhancement for more detailed status information.
</ParamField>

## Examples

### Basic Status

Get project status:

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

<Accordion title="Expected output">
  ```
  sudocode Status

  Specs:
    12 total

  Issues:
    47 total (15 open, 8 in_progress, 3 blocked, 5 needs_review, 16 closed)
    10 ready to work on
    3 blocked

  Sync status: All files in sync
  ```
</Accordion>

### JSON Output

Get machine-readable output for scripting:

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

<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
    }
  }
  ```
</Accordion>

## Output Explained

### Specs Section

```
Specs:
  12 total
```

* **total** - Total number of specifications in the project

### Issues Section

```
Issues:
  47 total (15 open, 8 in_progress, 3 blocked, 5 needs_review, 16 closed)
  10 ready to work on
  3 blocked
```

* **total** - Total number of issues (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

### Sync Status

```
Sync status: All files in sync
```

Indicates whether markdown files, JSONL, and database are synchronized.

## Common Workflows

### Daily Standup

<Steps>
  <Step title="Check status">
    ```bash theme={null}
    sudocode status
    ```
  </Step>

  <Step title="Report metrics">
    Share:

    * Issues in progress (what team is working on)
    * Issues needing review (what's ready for review)
    * Blocked count (bottlenecks)
    * Ready count (available work)
  </Step>

  <Step title="Plan work">
    Based on status, assign work:

    ```bash theme={null}
    sudocode ready
    ```
  </Step>
</Steps>

### Project Health Check

Regular monitoring:

```bash theme={null}
#!/bin/bash
# Daily status check

echo "Project Health - $(date)"
sudocode status

# Alert if too many blocked issues
blocked=$(sudocode --json status | jq '.issues.blocked')
if [ "$blocked" -gt 5 ]; then
  echo "⚠️  WARNING: High number of blocked issues ($blocked)"
fi

# Alert if no ready work
ready=$(sudocode --json status | jq '.issues.ready')
if [ "$ready" -eq 0 ]; then
  echo "⚠️  WARNING: No ready work available"
fi
```

### Weekly Progress Report

Track progress over time:

```bash theme={null}
#!/bin/bash
# Save status to log

echo "=== $(date) ===" >> status-log.txt
sudocode status >> status-log.txt
echo "" >> status-log.txt

# Calculate closed this week
closed_count=$(sudocode --json status | jq '.issues.by_status.closed')
echo "Issues closed this week: $closed_count"
```

## Comparing with Other Commands

<CardGroup cols={2}>
  <Card title="status" icon="chart-simple">
    **Quick overview**

    * High-level summary
    * Issue counts only
    * Fast execution
    * Daily standup use

    ```bash theme={null}
    sudocode status
    ```
  </Card>

  <Card title="stats" icon="chart-bar">
    **Detailed metrics**

    * Comprehensive statistics
    * Relationship counts
    * Recent activity
    * Project analysis

    ```bash theme={null}
    sudocode stats
    ```
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="ready" icon="circle-check">
    **Find available work**

    * Lists specific issues
    * Ready to start
    * Sorted by priority
    * Work selection

    ```bash theme={null}
    sudocode ready
    ```
  </Card>

  <Card title="blocked" icon="ban">
    **Find bottlenecks**

    * Lists blocked issues
    * Shows blocker IDs
    * Identifies problems
    * Prioritization aid

    ```bash theme={null}
    sudocode blocked
    ```
  </Card>
</CardGroup>

## Scripting Examples

### Status Dashboard

Create a visual dashboard:

```bash theme={null}
#!/bin/bash
clear
echo "╔════════════════════════════════════════╗"
echo "║      sudocode Project Dashboard       ║"
echo "╚════════════════════════════════════════╝"
echo ""

data=$(sudocode --json status)

# Specs
specs=$(echo "$data" | jq '.specs.total')
echo "📋 Specs: $specs"
echo ""

# Issues
total=$(echo "$data" | jq '.issues.total')
open=$(echo "$data" | jq '.issues.by_status.open')
in_progress=$(echo "$data" | jq '.issues.by_status.in_progress')
blocked=$(echo "$data" | jq '.issues.by_status.blocked')
needs_review=$(echo "$data" | jq '.issues.by_status.needs_review')
closed=$(echo "$data" | jq '.issues.by_status.closed')
ready=$(echo "$data" | jq '.issues.ready')

echo "📊 Issues: $total total"
echo "   ⚪ Open: $open"
echo "   🔵 In Progress: $in_progress"
echo "   🔴 Blocked: $blocked"
echo "   🟡 Needs Review: $needs_review"
echo "   ✅ Closed: $closed"
echo ""
echo "🚀 Ready to work: $ready"
echo "🚫 Blocked: $blocked"
```

### Status Change Alert

Monitor for changes:

```bash theme={null}
#!/bin/bash
# Alert on status changes

prev_file="/tmp/sudocode-status-prev.json"

# Get current status
current=$(sudocode --json status)

if [ -f "$prev_file" ]; then
  prev=$(cat "$prev_file")

  # Compare closed count
  prev_closed=$(echo "$prev" | jq '.issues.by_status.closed')
  curr_closed=$(echo "$current" | jq '.issues.by_status.closed')

  if [ "$curr_closed" -gt "$prev_closed" ]; then
    diff=$((curr_closed - prev_closed))
    echo "🎉 $diff issue(s) completed since last check!"
  fi

  # Compare blocked count
  prev_blocked=$(echo "$prev" | jq '.issues.blocked')
  curr_blocked=$(echo "$current" | jq '.issues.blocked')

  if [ "$curr_blocked" -gt "$prev_blocked" ]; then
    diff=$((curr_blocked - prev_blocked))
    echo "⚠️  $diff more issue(s) became blocked"
  fi
fi

# Save current status
echo "$current" > "$prev_file"
```

### Completion Rate

Calculate progress:

```bash theme={null}
#!/bin/bash
# Calculate completion percentage

data=$(sudocode --json status)

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

if [ "$total" -gt 0 ]; then
  percentage=$((closed * 100 / total))
  echo "Project completion: $percentage% ($closed/$total issues)"

  # Progress bar
  filled=$((percentage / 2))
  empty=$((50 - filled))
  printf "["
  printf "%${filled}s" | tr ' ' '█'
  printf "%${empty}s" | tr ' ' '░'
  printf "] $percentage%%\n"
fi
```

### Status Comparison

Compare with previous snapshot:

```bash theme={null}
#!/bin/bash
# Compare current status with yesterday

today=$(sudocode --json status)
yesterday=$(cat status-yesterday.json 2>/dev/null || echo '{}')

if [ -n "$yesterday" ] && [ "$yesterday" != "{}" ]; then
  echo "Status Changes (vs yesterday):"
  echo ""

  # Calculate deltas
  for status in open in_progress blocked needs_review closed; do
    today_count=$(echo "$today" | jq ".issues.by_status.$status")
    yesterday_count=$(echo "$yesterday" | jq ".issues.by_status.$status // 0")
    delta=$((today_count - yesterday_count))

    if [ "$delta" -gt 0 ]; then
      echo "  $status: +$delta"
    elif [ "$delta" -lt 0 ]; then
      echo "  $status: $delta"
    fi
  done
fi

# Save today's status
echo "$today" > status-yesterday.json
```

## Common Questions

<AccordionGroup>
  <Accordion title="What's the difference between status and stats?">
    * **status**: Quick overview, minimal information, fast
    * **stats**: Detailed metrics, relationship counts, recent activity

    Use `status` for daily checks, `stats` for in-depth analysis.
  </Accordion>

  <Accordion title="Why doesn't ready + blocked equal open?">
    **Ready** and **blocked** are subsets of different status categories:

    * **Ready**: Only `open` issues with no blockers
    * **Blocked**: Issues with status `open`, `in_progress`, OR `blocked`

    An `in_progress` issue can be blocked too.
  </Accordion>

  <Accordion title="Can I filter status by assignee?">
    Not directly. Use JSON output and process:

    ```bash theme={null}
    sudocode --json issue list --assignee alice | jq 'group_by(.status) | map({key: .[0].status, value: length}) | from_entries'
    ```
  </Accordion>

  <Accordion title="What does 'All files in sync' mean?">
    It means the markdown files, JSONL files, and database are all consistent. If out of sync, run:

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

  <Accordion title="Can I see status for a specific date range?">
    Not with this command. For historical analysis, you'd need to:

    1. Save status snapshots over time
    2. Query JSONL history
    3. Use git history of `.sudocode/` directory
  </Accordion>

  <Accordion title="How often should I check status?">
    Depends on project pace:

    * **Daily**: Active projects with multiple team members
    * **Weekly**: Slower-paced projects
    * **Before standups**: Always check before meetings

    Consider automating with a cron job.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Status shows 0 for everything">
    **Cause:** No data in database or not in sudocode 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="Counts don't add up correctly">
    **Cause:** Database inconsistency

    **Solution:**

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

  <Accordion title="Sync status shows 'out of sync'">
    **Cause:** Markdown/JSONL changes not reflected in database

    **Solution:**

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

  <Accordion title="Ready count seems wrong">
    **Cause:** Ready count only includes open issues with no blockers

    **Solution:**
    Verify with:

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

    Check individual issues for blocker relationships.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="stats" icon="chart-bar" href="/cli/stats">
    Detailed project statistics
  </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="Check status">
    ```bash theme={null}
    sudocode status
    ```
  </Step>

  <Step title="If issues are ready">
    ```bash theme={null}
    sudocode ready
    ```

    Claim and start work
  </Step>

  <Step title="If issues are blocked">
    ```bash theme={null}
    sudocode blocked
    ```

    Prioritize unblocking work
  </Step>

  <Step title="For detailed analysis">
    ```bash theme={null}
    sudocode stats
    ```

    Deep dive into project metrics
  </Step>
</Steps>

<Card title="Project Workflows" icon="book" href="/concepts/workflows">
  Learn more about effective sudocode workflows
</Card>