Jules and the Lobster API headless

# 0. Set your API key (required — get one at https://jules.google.com/settings#api)
export JULES_API_KEY="your-api-key-here"
1. Verify available sources (pre-flight check)
./scripts/jules_api.sh sources
2. Create a session with plan approval and auto PR creation
./scripts/jules_api.sh new-session \
  --source "sources/github/OWNER/REPO" \
  --title "Add unit tests" \
  --prompt "Add comprehensive unit tests for the authentication module" \
  --branch main \
  --require-plan-approval \
  --auto-pr
3. Monitor session progress and approve the plan
./scripts/jules_api.sh activities --session SESSION_ID
./scripts/jules_api.sh approve-plan --session SESSION_ID

Note: Use your GitHub username/org, not your local system username (e.g., sources/github/octocat/Hello-World, not sources/github/$USER/Hello-World).

Writing Effective Prompts

1. Be specific: Instead of "fix the bug", say "fix the null pointer exception in auth.js:45 when email is undefined" 2. Provide context: Mention relevant files, functions, or error messages 3. Keep tasks focused: One logical task per session

Monitoring Sessions

1. Poll session state to track progress 2. Check activities for detailed progress updates 3. Handle AWAITING_USER_FEEDBACK state by sending clarifying messages

Security

1. Never include secrets or credentials in prompts 2. Review generated PRs before merging 3. Use requirePlanApproval: true (recommended for all repos, especially production) 4. Only install the Jules GitHub app on repositories you intend to use with Jules — limit access scope 5. Treat JULES_API_KEY as a secret: store it securely, rotate it regularly, and never paste it into untrusted places

Performance

1. Use automationMode: AUTO_CREATE_PR for streamlined workflows 2. Only skip plan approval (requirePlanApproval: false) for routine, low-risk tasks in non-critical repos 3. Break complex tasks into smaller sessions