sudocode status

Syntax

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

Use status for a quick overview. For detailed statistics and metrics, use stats instead.

Options

boolean

Show detailed output (not currently implemented)Example: --verboseFuture enhancement for more detailed status information.

Examples

Basic Status

Get project status:

sudocode status

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

JSON Output

Get machine-readable output for scripting:

sudocode --json status

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
  }
}

Output Explained

Specs Section

Specs:
  12 total

total - Total number of specifications in the project

Issues Section

Issues:
total (15 open, 8 in_progress, 3 blocked, 5 needs_review, 16 closed)
ready to work on
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

Check status

sudocode status

Report metrics

Issues in progress (what team is working on)
Issues needing review (what’s ready for review)
Blocked count (bottlenecks)
Ready count (available work)

Plan work

Based on status, assign work:

sudocode ready

Project Health Check

Regular monitoring:

#!/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:

#!/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

status

Quick overview

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

sudocode status

stats

Detailed metrics

Comprehensive statistics
Relationship counts
Recent activity
Project analysis

sudocode stats

ready

Find available work

Lists specific issues
Ready to start
Sorted by priority
Work selection

sudocode ready

blocked

Find bottlenecks

Lists blocked issues
Shows blocker IDs
Identifies problems
Prioritization aid

sudocode blocked

Scripting Examples

Status Dashboard

Create a visual dashboard:

#!/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:

#!/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:

#!/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:

#!/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

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.

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.

Can I filter status by assignee?

Not directly. Use JSON output and process:

sudocode --json issue list --assignee alice | jq 'group_by(.status) | map({key: .[0].status, value: length}) | from_entries'

What does 'All files in sync' mean?

It means the markdown files, JSONL files, and database are all consistent. If out of sync, run:

sudocode sync

Can I see status for a specific date range?

Not with this command. For historical analysis, you’d need to:

Save status snapshots over time
Query JSONL history
Use git history of .sudocode/ directory

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.

Troubleshooting

Status shows 0 for everything

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

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

Counts don't add up correctly

Cause: Database inconsistencySolution:

sudocode sync
sudocode status

Sync status shows 'out of sync'

Cause: Markdown/JSONL changes not reflected in databaseSolution:

sudocode sync

Ready count seems wrong

Cause: Ready count only includes open issues with no blockersSolution: Verify with:

sudocode ready

Check individual issues for blocker relationships.

stats

Detailed project statistics

ready

Find ready work

blocked

Find blocked issues

issue list

List all issues

spec list

List all specs

Next Steps

Check status

sudocode status

If issues are ready

sudocode ready

Claim and start work

If issues are blocked

sudocode blocked

Prioritize unblocking work

For detailed analysis

sudocode stats

Deep dive into project metrics

Project Workflows

Learn more about effective sudocode workflows

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Syntax

Description

Options

Examples

Basic Status

JSON Output

Output Explained

Specs Section

Issues Section

Sync Status

Common Workflows

Daily Standup

Project Health Check

Weekly Progress Report

Comparing with Other Commands

status

stats

ready

blocked

Scripting Examples

Status Dashboard

Status Change Alert

Completion Rate

Status Comparison

Common Questions

Troubleshooting

stats

ready

blocked

issue list

spec list

Next Steps

Project Workflows

​Syntax

​Description

​Options

​Examples

​Basic Status

​JSON Output

​Output Explained

​Specs Section

​Issues Section

​Sync Status

​Common Workflows

​Daily Standup

​Project Health Check

​Weekly Progress Report

​Comparing with Other Commands

status

stats

ready

blocked

​Scripting Examples

​Status Dashboard

​Status Change Alert

​Completion Rate

​Status Comparison

​Common Questions

​Troubleshooting

​Related Commands

stats

ready

blocked

issue list

spec list

​Next Steps

Project Workflows

Syntax

Description

Options

Examples

Basic Status

JSON Output

Output Explained

Specs Section

Issues Section

Sync Status

Common Workflows

Daily Standup

Project Health Check

Weekly Progress Report

Comparing with Other Commands

Scripting Examples

Status Dashboard

Status Change Alert

Completion Rate

Status Comparison

Common Questions

Troubleshooting

Related Commands

Next Steps