Handling Blocked Tasks

How to help Claude when it gets stuck

Handling Blocked Tasks

Sometimes Claude needs your help to continue. This is the "human in the loop" feature that makes Claudear practical for real development work.

When Does Claude Get Blocked?

Claude will pause and ask for help when:

Missing information - The task description is unclear
Access issues - Can't access a file or resource
Design decisions - Multiple valid approaches exist
Permission errors - Needs credentials or API keys
Ambiguous requirements - Needs clarification

How It Works

1. Claude Detects a Blocker

When Claude encounters an issue, it outputs:

BLOCKED: Need clarification on the authentication flow.
Should we use JWT tokens or session cookies?

2. Claudear Posts a Comment

On Linear: A comment appears on your Linear issue:

Claudear is blocked

Reason: Need clarification on the authentication flow. Should we use JWT tokens or session cookies?

Please respond with guidance to continue.

On Notion: A comment appears on your Notion page with similar content, and the "Blocked" checkbox is set to true.

3. You Respond

Reply to the comment with your guidance:

Use JWT tokens. Store them in httpOnly cookies for security. The refresh token endpoint is at /api/auth/refresh.

4. Claude Resumes

Claudear detects your comment and:

Sends your response to Claude
Claude continues the task
Task stays in "In Progress"

Best Practices

Writing Good Unblock Responses

Be specific:

Use the existing UserService class in src/services/user.ts.
The createUser method should validate email format.

Provide examples:

Follow the pattern in src/api/products.ts for the new endpoint.
Error responses should use the format: { error: string, code: number }

Reference files:

See the auth flow in docs/AUTHENTICATION.md for context.
Use the same approach as the login endpoint.

What to Avoid

Vague responses like "make it work" or "figure it out"
Changing requirements mid-task
Referencing external docs without summarizing

Automatic Detection

Claudear detects blocks through keyword matching:

BLOCKED:
I need clarification
I cannot proceed
permission denied
missing information

Claude is trained to use these phrases when stuck.

Timeout Handling

If you don't respond within the timeout period (default: 1 hour):

Task enters FAILED state
Comment posted with timeout message
Worktree preserved for debugging

To adjust the timeout:

BLOCKED_TIMEOUT=7200  # 2 hours

Provider-Specific Notes

Linear

Comments appear in the issue activity
Claudear filters out its own comments
Human comments trigger unblock

Notion

Comments appear in the page's comment section
"Blocked" checkbox is set to true
"Current Status" shows the block reason

Monitoring Blocked Tasks

Check blocked tasks in logs:

[INFO] Task ENG-123 is blocked: Need API endpoint specification
[INFO] Waiting for human response...

Manual Intervention

If the comment polling misses your response, you can:

Check the comment was posted correctly
Wait for the next poll cycle (default: 30 seconds)
If still stuck, restart Claudear

To adjust polling frequency:

COMMENT_POLL_INTERVAL=10  # Check every 10 seconds