Skip to main content

​
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

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

​
Examples

​
Basic Status

Get project status: 
sudocode status

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

{
  "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:
  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

1

Check status

sudocode status
2

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)
3

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

  • status: Quick overview, minimal information, fast
  • stats: Detailed metrics, relationship counts, recent activity
Use status for daily checks, stats for in-depth analysis.
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.
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'
It means the markdown files, JSONL files, and database are all consistent. If out of sync, run:
sudocode sync
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
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

Cause: No data in database or not in sudocode project directorySolution:
  1. Verify you’re in project root
  2. Check .sudocode/ directory exists
  3. Run sync: 
    sudocode sync
Cause: Database inconsistencySolution:
sudocode sync
sudocode status
Cause: Markdown/JSONL changes not reflected in databaseSolution:
sudocode sync
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

1

Check status

sudocode status
2

If issues are ready

sudocode ready
Claim and start work
3

If issues are blocked

sudocode blocked
Prioritize unblocking work
4

For detailed analysis

sudocode stats
Deep dive into project metrics

Project Workflows

Learn more about effective sudocode workflows