Skip to main content

Syntax

sudocode ready [options]

Description

The ready command identifies issues that are ready for immediate work. These are issues that:
  • Have status open (not already in progress or closed)
  • Are not archived
  • Have no active blocking relationships (or all blockers are closed)
This command is essential for:
  • Finding next work to start
  • Agent task selection
  • Daily planning and prioritization
  • Identifying available work for team members
“Ready” means the issue has no dependencies blocking it. Use this to find work you can start immediately without waiting for other issues.

How “Ready” is Determined

An issue is considered ready when:
1

Status is open

The issue must have status = 'open'Issues that are in_progress, needs_review, or closed are excluded.
2

Not archived

The issue must not be archived (archived = 0)
3

No active blockers

Either:
  • The issue has no “blocks” relationships pointing to it, OR
  • All issues blocking it have status = 'closed'
If any blocker is still open, in_progress, or blocked, the issue is not ready.

Ready Issues View

The command queries the ready_issues database view:
SELECT i.*
FROM issues i
WHERE i.status = 'open'
  AND i.archived = 0
  AND NOT EXISTS (
    SELECT 1 FROM relationships r
    JOIN issues blocker ON r.to_id = blocker.id
    WHERE r.from_id = i.id
      AND r.from_type = 'issue'
      AND r.to_type = 'issue'
      AND r.relationship_type = 'blocks'
      AND blocker.status IN ('open', 'in_progress', 'blocked')
  )
ORDER BY priority DESC, created_at DESC;
This ensures only truly unblocked work is shown.

Examples

Find Ready Issues

List all issues ready to work on:
sudocode ready
Ready Issues (3):

ISSUE-005 Implement OAuth 2.0 authentication @alice
  Priority: 0

ISSUE-008 Add rate limiting to API endpoints
  Priority: 1

ISSUE-012 Write integration tests for auth flow @bob
  Priority: 2

No Ready Issues

When all issues are blocked or completed:
sudocode ready
No ready issues

JSON Output

Get machine-readable output for scripting:
sudocode --json ready
{
  "issues": [
    {
      "id": "ISSUE-005",
      "uuid": "a1b2c3...",
      "title": "Implement OAuth 2.0 authentication",
      "content": "...",
      "status": "open",
      "priority": 0,
      "assignee": "alice",
      "archived": 0,
      "created_at": "2025-10-29T08:00:00Z",
      "updated_at": "2025-10-29T09:00:00Z",
      "closed_at": null,
      "parent_id": null
    },
    {
      "id": "ISSUE-008",
      "uuid": "d4e5f6...",
      "title": "Add rate limiting to API endpoints",
      "content": "...",
      "status": "open",
      "priority": 1,
      "assignee": null,
      "archived": 0,
      "created_at": "2025-10-28T14:00:00Z",
      "updated_at": "2025-10-28T14:00:00Z",
      "closed_at": null,
      "parent_id": null
    }
  ]
}

Output Format

Ready issues are displayed with:
  • Issue ID (cyan) - The unique identifier
  • Title - Issue description
  • Assignee (gray) - If assigned, shown as @username
  • Priority - Lower number = higher priority (0 is highest)
Issues are sorted by:
  1. Priority (descending) - Highest priority first
  2. Created date (descending) - Older issues first within same priority

Common Workflows

Daily Work Selection

1

Check ready work

sudocode ready
2

Choose highest priority

Pick the first issue (highest priority)
3

Claim the work

sudocode issue update ISSUE-005 --status in_progress --assignee alice
4

Start implementation

Begin working on the issue

Agent Workflow

Automated agent claiming work:
#!/bin/bash
# Agent script to claim and start work

# Get first ready issue
issue_id=$(sudocode --json ready | jq -r '.issues[0].id')

if [ -n "$issue_id" ] && [ "$issue_id" != "null" ]; then
  echo "Claiming $issue_id"

  # Update status and assignee
  sudocode issue update "$issue_id" \
    --status in_progress \
    --assignee "agent-01"

  # Read the issue details
  sudocode issue show "$issue_id"

  # Start implementation
  # ... agent implementation logic ...
else
  echo "No ready work available"
fi

Filter by Priority

Find only high-priority ready work:
# Get ready issues
sudocode --json ready | jq '.issues[] | select(.priority <= 1)'
This shows only issues with priority 0 or 1.

Check for Specific Assignee

See what’s ready for a specific person:
# Get unassigned ready work
sudocode --json ready | jq '.issues[] | select(.assignee == null)'

# Get work assigned to alice
sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'

Understanding Blockers

Why an Issue Might Not Be Ready

Scenario: ISSUE-010 has blocks relationship to ISSUE-005Result: ISSUE-005 won’t appear in ready list until ISSUE-010 is closedCheck blockers:
sudocode issue show ISSUE-005
Look for “Incoming Relationships” with type “blocks”
Scenario: Issue is in_progress or closedResult: Only open issues appear in ready listCheck status:
sudocode issue show ISSUE-005
Scenario: Issue was archivedResult: Archived issues are excluded from ready listCheck archive status:
sudocode issue show ISSUE-005
Look for archived: true
Scenario: Blocker was just closed but database not syncedResult: May not appear in ready list yetSolution:
sudocode sync
sudocode ready

Making Issues Ready

To make a blocked issue ready:
1

Find the blockers

sudocode issue show ISSUE-005
Check “Incoming Relationships” for blocks
2

Complete blocker issues

Work on and close the blocking issues:
sudocode issue close ISSUE-010
3

Verify now ready

sudocode ready
ISSUE-005 should now appear

ready

Find available work
  • Shows open issues only
  • No active blockers
  • Sorted by priority
  • Ready to start immediately
sudocode ready

blocked

Find blocked work
  • Shows blocked issues
  • Lists what blocks them
  • Identifies bottlenecks
  • Cannot start yet
sudocode blocked

issue list --status open

All open issues
  • Shows ALL open issues
  • Includes blocked ones
  • More filtering options
  • General issue browsing
sudocode issue list --status open

status

Project overview
  • Shows ready count
  • Shows blocked count
  • Project-wide statistics
  • Quick health check
sudocode status

Scripting Examples

Auto-assign Ready Work

Automatically assign ready issues to agents:
#!/bin/bash
agents=("agent-01" "agent-02" "agent-03")
agent_index=0

sudocode --json ready | jq -r '.issues[] | select(.assignee == null) | .id' | \
while read issue_id; do
  agent="${agents[$agent_index]}"
  echo "Assigning $issue_id to $agent"

  sudocode issue update "$issue_id" --assignee "$agent"

  agent_index=$(( (agent_index + 1) % ${#agents[@]} ))
done

Ready Work Digest

Generate a daily ready work report:
#!/bin/bash
echo "Ready Work Report - $(date)"
echo "============================"
echo ""

count=$(sudocode --json ready | jq '.issues | length')
echo "Total ready issues: $count"
echo ""

if [ "$count" -gt 0 ]; then
  echo "By Priority:"
  for p in 0 1 2 3 4; do
    p_count=$(sudocode --json ready | jq ".issues[] | select(.priority == $p)" | jq -s 'length')
    if [ "$p_count" -gt 0 ]; then
      echo "  Priority $p: $p_count issues"
    fi
  done

  echo ""
  echo "Unassigned: $(sudocode --json ready | jq '.issues[] | select(.assignee == null)' | jq -s 'length')"
fi

Monitor Ready Work

Check if ready work becomes available:
#!/bin/bash
# Run periodically to alert when work becomes ready

prev_count=0
while true; do
  count=$(sudocode --json ready | jq '.issues | length')

  if [ "$count" -gt "$prev_count" ]; then
    echo "$(date): New ready work available! ($count issues)"
    sudocode ready
  fi

  prev_count=$count
  sleep 300  # Check every 5 minutes
done

Common Questions

Check these conditions:
  1. Status must be open
  2. Must not be archived
  3. No open/in_progress blockers
Run:
sudocode issue show ISSUE-005
sudocode blocked
Not directly, but use JSON output with jq:
sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'
Some ready issues may require specific skills or context. Consider:
  • Adding assignee field to track who should work on it
  • Using priority to indicate difficulty
  • Adding tags for skill requirements
The list is already sorted by priority (highest first), then by creation date (oldest first). To change priority:
sudocode issue update ISSUE-005 --priority 0
Yes, use the JSON output to build automation:
issue_id=$(sudocode --json ready | jq -r '.issues[0].id')
sudocode issue update "$issue_id" --status in_progress --assignee "agent-01"
  • ready: Only shows open issues with NO blockers
  • issue list —status open: Shows ALL open issues, including blocked ones
Use ready when you want to find work you can start immediately.

Troubleshooting

Cause: All open issues are blockedSolution: Check blocked issues:
sudocode blocked
Complete blocker issues to make them ready.
Cause: Database may be out of syncSolution: Run sync:
sudocode sync
sudocode ready
Cause: Database view not refreshedSolution: Views should update automatically. If not:
sudocode sync
Cause: Need better prioritizationSolution: Use priority field:
# Set high priority
sudocode issue update ISSUE-005 --priority 0

# Ready list automatically sorts by priority
sudocode ready

Next Steps

1

Find ready work

sudocode ready
2

Choose an issue

Select based on priority and your skills
3

Claim the work

sudocode issue update ISSUE-005 --status in_progress --assignee alice
4

View details

sudocode issue show ISSUE-005
5

Start implementation

Begin working on the issue

Issues Concept Guide

Learn more about issue lifecycle and workflows