Syntax
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:
Status is open
The issue must have status = 'open' Issues that are in_progress, needs_review, or closed are excluded.
Not archived
The issue must not be archived (archived = 0)
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:
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:
JSON Output
Get machine-readable output for scripting:
{
"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
}
]
}
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:
Priority (descending) - Highest priority first
Created date (descending) - Older issues first within same priority
Common Workflows
Daily Work Selection
Choose highest priority
Pick the first issue (highest priority)
Claim the work
sudocode issue update ISSUE-005 --status in_progress --assignee alice
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
Blocker was completed recently
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:
Find the blockers
sudocode issue show ISSUE-005
Check “Incoming Relationships” for blocks
Complete blocker issues
Work on and close the blocking issues: sudocode issue close ISSUE-010
Verify now ready
ISSUE-005 should now appear
ready Find available work
Shows open issues only
No active blockers
Sorted by priority
Ready to start immediately
blocked Find blocked work
Shows blocked issues
Lists what blocks them
Identifies bottlenecks
Cannot start yet
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
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
Why doesn't my issue appear in ready list?
Check these conditions:
Status must be open
Must not be archived
No open/in_progress blockers
Run: sudocode issue show ISSUE-005
sudocode blocked
Can I filter ready issues by assignee?
Not directly, but use JSON output with jq: sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'
What if ready shows issues I can't work on?
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
How do I prioritize within ready list?
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
Can agents automatically claim ready work?
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"
What's the difference between ready and issue list --status open?
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
Ready list is empty but I know there are open issues
Cause: All open issues are blockedSolution:
Check blocked issues:Complete blocker issues to make them ready.
Issue appears ready but shows as blocked in issue show
Cause: Database may be out of syncSolution:
Run sync:sudocode sync
sudocode ready
Just closed a blocker but dependent issue not showing as ready
Cause: Database view not refreshedSolution:
Views should update automatically. If not:
Too many ready issues, hard to choose
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
Choose an issue
Select based on priority and your skills
Claim the work
sudocode issue update ISSUE-005 --status in_progress --assignee alice
View details
sudocode issue show ISSUE-005
Start implementation
Begin working on the issue
Issues Concept Guide Learn more about issue lifecycle and workflows