{
  "schemaVersion": "1.0",
  "item": {
    "slug": "jules-and-lobster",
    "name": "Jules and the Lobster API headless",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/SanJacob99/jules-and-lobster",
    "canonicalUrl": "https://clawhub.ai/SanJacob99/jules-and-lobster",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/jules-and-lobster",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=jules-and-lobster",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "scripts/jules.js",
      "scripts/jules_api.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/jules-and-lobster"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/jules-and-lobster",
    "agentPageUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent",
    "manifestUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Quick Start",
        "body": "# 0. Set your API key (required — get one at https://jules.google.com/settings#api)\nexport JULES_API_KEY=\"your-api-key-here\"\n\n# 1. Verify available sources (pre-flight check)\n./scripts/jules_api.sh sources\n\n# 2. Create a session with plan approval and auto PR creation\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/OWNER/REPO\" \\\n  --title \"Add unit tests\" \\\n  --prompt \"Add comprehensive unit tests for the authentication module\" \\\n  --branch main \\\n  --require-plan-approval \\\n  --auto-pr\n\n# 3. Monitor session progress and approve the plan\n./scripts/jules_api.sh activities --session SESSION_ID\n./scripts/jules_api.sh approve-plan --session SESSION_ID\n\nNote: Use your GitHub username/org, not your local system username (e.g., sources/github/octocat/Hello-World, not sources/github/$USER/Hello-World)."
      },
      {
        "title": "Overview",
        "body": "This skill enables programmatic interaction with the Jules REST API (v1alpha) for delegating coding tasks to Jules, Google's autonomous AI coding agent. It supports:\n\nTask Assignment: Create new coding sessions with specific prompts\nSession Monitoring: Track session state and activities in real-time\nPlan Management: Approve or review generated plans\nMessaging: Send follow-up messages to active sessions\nResult Integration: Retrieve PR URLs and code changes from completed sessions"
      },
      {
        "title": "1. Get an API Key",
        "body": "Create a Jules API key in the Jules web app:\n\nNavigate to: https://jules.google.com/settings#api\nYou can have at most 3 API keys at a time\n\nExport it on the machine running the agent:\n\nexport JULES_API_KEY=\"your-api-key-here\""
      },
      {
        "title": "2. Connect Your GitHub Repository",
        "body": "Before the API can operate on a GitHub repo, you must:\n\nInstall the Jules GitHub app via the Jules web UI\nGrant access to the specific repositories you want Jules to work on"
      },
      {
        "title": "3. Verify Repository Access",
        "body": "# List available sources to verify access and see correct format\n./scripts/jules_api.sh sources\n\nYou'll see entries like:\n\n{\n  \"sources\": [\n    {\n      \"name\": \"sources/github/octocat/Hello-World\",\n      \"githubRepo\": {\n        \"owner\": \"octocat\",\n        \"repo\": \"Hello-World\",\n        \"defaultBranch\": { \"displayName\": \"main\" },\n        \"branches\": [\n          { \"displayName\": \"main\" },\n          { \"displayName\": \"develop\" }\n        ]\n      }\n    }\n  ]\n}"
      },
      {
        "title": "Base URL & Authentication",
        "body": "PropertyValueBase URLhttps://jules.googleapis.com/v1alphaAuth Headerx-goog-api-key: $JULES_API_KEY\n\nAll requests authenticate with:\n\n-H \"x-goog-api-key: $JULES_API_KEY\""
      },
      {
        "title": "Resources",
        "body": "ResourceDescriptionSourceA GitHub repository connected to Jules. Format: sources/github/{owner}/{repo}SessionA unit of work where Jules executes a coding task. Contains state, activities, and outputsActivityAn individual event within a session (plan generated, message sent, progress update, etc.)"
      },
      {
        "title": "Session States",
        "body": "StateDescriptionQUEUEDSession is waiting to startPLANNINGGenerating execution planAWAITING_PLAN_APPROVALWaiting for user to approve planAWAITING_USER_FEEDBACKNeeds user input to continueIN_PROGRESSActively executing the taskPAUSEDTemporarily stoppedCOMPLETEDSuccessfully finishedFAILEDEncountered an error"
      },
      {
        "title": "Activity Types",
        "body": "TypeDescriptionPlan GeneratedA plan was generated for the taskPlan ApprovedThe plan was approved (manually or auto)User MessageUser posted a message to the sessionAgent MessageJules posted a messageProgress UpdateStatus update on current workSession CompletedSession finished successfullySession FailedSession encountered an error"
      },
      {
        "title": "Option 1: Session with Plan Approval and Auto-PR (Recommended)",
        "body": "Create a session that requires plan approval before execution and automatically creates a PR when complete:\n\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Fix login bug\" \\\n  --prompt \"Fix the null pointer exception in the login handler when email is empty\" \\\n  --branch main \\\n  --require-plan-approval \\\n  --auto-pr\n\nWhy this is recommended:\n\nYou review and approve the plan before Jules executes changes\nPR is created automatically on completion\nBalances automation with human oversight"
      },
      {
        "title": "Option 2: Fully Automated Session (No Plan Approval)",
        "body": "For low-risk or routine tasks in non-sensitive repos, you can skip plan approval:\n\n# Create session without plan approval (use only for low-risk tasks)\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Fix typo in README\" \\\n  --prompt \"Fix the typo in README.md line 5\" \\\n  --branch main \\\n  --auto-pr\n\nWarning: Without --require-plan-approval, Jules will automatically approve its own plan and execute changes. Only use this for low-risk tasks in non-critical repos."
      },
      {
        "title": "Option 3: Interactive Session",
        "body": "Send follow-up messages during an active session:\n\n# Create session\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Add API endpoints\" \\\n  --prompt \"Add REST API endpoints for user management\" \\\n  --branch main\n\n# Send additional instructions\n./scripts/jules_api.sh send-message \\\n  --session SESSION_ID \\\n  --prompt \"Also add input validation for all endpoints\""
      },
      {
        "title": "Sources",
        "body": "List Sources\n\nLists all connected GitHub repositories.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sources\"\n\nQuery Parameters:\n\nParameterTypeDefaultDescriptionpageSizeinteger30Number of sources to return (1-100)pageTokenstring-Token from previous response for paginationfilterstring-AIP-160 filter (e.g., name=sources/source1)\n\nResponse:\n\n{\n  \"sources\": [\n    {\n      \"name\": \"sources/github/octocat/Hello-World\",\n      \"githubRepo\": {\n        \"owner\": \"octocat\",\n        \"repo\": \"Hello-World\",\n        \"isPrivate\": false,\n        \"defaultBranch\": { \"displayName\": \"main\" },\n        \"branches\": [\n          { \"displayName\": \"main\" },\n          { \"displayName\": \"develop\" }\n        ]\n      }\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n\nGet Source\n\nRetrieves a single source by name.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sources/github/octocat/Hello-World\"\n\nUse this to see available branches before creating a session."
      },
      {
        "title": "Sessions",
        "body": "Create Session\n\nCreates a new coding session.\n\ncurl -sS \"https://jules.googleapis.com/v1alpha/sessions\" \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  -d '{\n    \"prompt\": \"Add unit tests for the login module\",\n    \"title\": \"Add Login Tests\",\n    \"sourceContext\": {\n      \"source\": \"sources/github/octocat/Hello-World\",\n      \"githubRepoContext\": {\n        \"startingBranch\": \"main\"\n      }\n    },\n    \"requirePlanApproval\": true,\n    \"automationMode\": \"AUTO_CREATE_PR\"\n  }'\n\nRequest Body Fields:\n\nFieldTypeRequiredDescriptionpromptstringYesThe task description for JulestitlestringNoShort title for the sessionsourceContext.sourcestringYesSource name (e.g., sources/github/owner/repo)sourceContext.githubRepoContext.startingBranchstringYesBranch to start fromrequirePlanApprovalbooleanNoIf true, pause for plan approval. Recommended: true for production reposautomationModestringNoSet to AUTO_CREATE_PR for automatic PR creation\n\nResponse:\n\n{\n  \"name\": \"sessions/31415926535897932384\",\n  \"id\": \"31415926535897932384\",\n  \"prompt\": \"Add unit tests for the login module\",\n  \"title\": \"Add Login Tests\",\n  \"state\": \"QUEUED\",\n  \"url\": \"https://jules.google/session/31415926535897932384\",\n  \"createTime\": \"2026-01-15T10:30:00Z\",\n  \"updateTime\": \"2026-01-15T10:30:00Z\"\n}\n\nList Sessions\n\nLists your sessions.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions?pageSize=20\"\n\nQuery Parameters:\n\nParameterTypeDefaultDescriptionpageSizeinteger30Number of sessions to return (1-100)pageTokenstring-Token from previous response for pagination\n\nGet Session\n\nRetrieves a single session by ID.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\"\n\nResponse includes outputs on completion:\n\n{\n  \"name\": \"sessions/31415926535897932384\",\n  \"id\": \"31415926535897932384\",\n  \"state\": \"COMPLETED\",\n  \"outputs\": [\n    {\n      \"pullRequest\": {\n        \"url\": \"https://github.com/octocat/Hello-World/pull/42\",\n        \"title\": \"Add Login Tests\",\n        \"description\": \"This PR adds comprehensive unit tests...\"\n      }\n    }\n  ]\n}\n\nSend Message\n\nSends a message to an active session.\n\ncurl -sS \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage\" \\\n  -d '{\"prompt\": \"Also add integration tests\"}'\n\nUse this to provide feedback, answer questions, or give additional instructions.\n\nApprove Plan\n\nApproves a pending plan (only needed if requirePlanApproval was true).\n\ncurl -sS \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan\"\n\nDelete Session\n\nDeletes a session.\n\ncurl -sS \\\n  -X DELETE \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\""
      },
      {
        "title": "Activities",
        "body": "List Activities\n\nLists activities for a session.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=30\"\n\nQuery Parameters:\n\nParameterTypeDefaultDescriptionpageSizeinteger50Number of activities to return (1-100)pageTokenstring-Token from previous response for pagination\n\nResponse:\n\n{\n  \"activities\": [\n    {\n      \"name\": \"sessions/123/activities/456\",\n      \"createTime\": \"2026-01-15T10:31:00Z\",\n      \"planGenerated\": {\n        \"plan\": \"1. Analyze existing code\\n2. Create test files\\n3. Write tests...\"\n      }\n    },\n    {\n      \"name\": \"sessions/123/activities/457\",\n      \"createTime\": \"2026-01-15T10:32:00Z\",\n      \"progressUpdate\": {\n        \"title\": \"Writing tests\",\n        \"details\": \"Creating test file for auth module...\"\n      }\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n\nActivities may include artifacts with code changes:\n\n{\n  \"artifacts\": [\n    {\n      \"changeSet\": {\n        \"gitPatch\": {\n          \"unidiffPatch\": \"diff --git a/...\",\n          \"baseCommitId\": \"abc123\",\n          \"suggestedCommitMessage\": \"Add unit tests for login\"\n        }\n      }\n    }\n  ]\n}\n\nGet Activity\n\nRetrieves a single activity by ID.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities/ACTIVITY_ID\""
      },
      {
        "title": "jules_api.sh",
        "body": "The scripts/jules_api.sh script provides a convenient wrapper for common API operations.\n\nUsage:\n\n# List sources\n./scripts/jules_api.sh sources\n\n# List sessions\n./scripts/jules_api.sh sessions [--page-size N]\n\n# List activities for a session\n./scripts/jules_api.sh activities --session <id> [--page-size N]\n\n# Send message to session\n./scripts/jules_api.sh send-message --session <id> --prompt \"...\"\n\n# Approve plan\n./scripts/jules_api.sh approve-plan --session <id>\n\n# Create new session\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/owner/repo\" \\\n  --title \"...\" \\\n  --prompt \"...\" \\\n  [--branch main] \\\n  [--auto-pr] \\\n  [--no-plan-approval]\n\nFlags:\n\nFlagDescription--sourceSource name (format: sources/github/owner/repo)--titleSession title--promptTask description or message content--sessionSession ID--branchStarting branch (default: main)--auto-prEnable automatic PR creation--require-plan-approvalRequire explicit plan approval (default)--no-plan-approvalSkip plan approval (use for low-risk tasks only)--page-sizeNumber of results to return"
      },
      {
        "title": "jules.js",
        "body": "The scripts/jules.js script wraps the Jules CLI for programmatic use.\n\nUsage:\n\nnode scripts/jules.js version\nnode scripts/jules.js list-repos\nnode scripts/jules.js list-sessions\nnode scripts/jules.js new --repo owner/repo --task \"Your task\"\nnode scripts/jules.js pull --session SESSION_ID"
      },
      {
        "title": "\"Source not found\" or \"Repository not found\"",
        "body": "Cause: Repository not connected or incorrect source name format.\n\nSolution:\n\nRun ./scripts/jules_api.sh sources to list available sources\nEnsure you've installed the Jules GitHub app for this repo\nUse the exact source name from the list (e.g., sources/github/octocat/Hello-World)"
      },
      {
        "title": "\"Missing JULES_API_KEY\"",
        "body": "Cause: API key not set in environment.\n\nSolution:\n\nexport JULES_API_KEY=\"your-api-key\""
      },
      {
        "title": "Authentication Errors",
        "body": "Cause: Invalid or expired API key.\n\nSolution:\n\nGenerate a new API key at https://jules.google.com/settings#api\nUpdate the JULES_API_KEY environment variable\nNote: You can have at most 3 API keys at a time"
      },
      {
        "title": "Session Stuck in AWAITING_PLAN_APPROVAL",
        "body": "Cause: Session was created with requirePlanApproval: true.\n\nSolution:\n\n./scripts/jules_api.sh approve-plan --session SESSION_ID"
      },
      {
        "title": "Task Fails with Vague Error",
        "body": "Cause: Vague prompts may produce unexpected results.\n\nSolution:\n\nWrite clear, specific prompts\nBreak large tasks into smaller, focused tasks\nAvoid prompts that require long-running commands (dev servers, watch scripts)"
      },
      {
        "title": "Large Files Skipped",
        "body": "Cause: Files exceeding 768,000 tokens may be skipped.\n\nSolution:\n\nBreak down operations on very large files\nConsider splitting large files before processing"
      },
      {
        "title": "Writing Effective Prompts",
        "body": "Be specific: Instead of \"fix the bug\", say \"fix the null pointer exception in auth.js:45 when email is undefined\"\nProvide context: Mention relevant files, functions, or error messages\nKeep tasks focused: One logical task per session"
      },
      {
        "title": "Monitoring Sessions",
        "body": "Poll session state to track progress\nCheck activities for detailed progress updates\nHandle AWAITING_USER_FEEDBACK state by sending clarifying messages"
      },
      {
        "title": "Security",
        "body": "Never include secrets or credentials in prompts\nReview generated PRs before merging\nUse requirePlanApproval: true (recommended for all repos, especially production)\nOnly install the Jules GitHub app on repositories you intend to use with Jules — limit access scope\nTreat JULES_API_KEY as a secret: store it securely, rotate it regularly, and never paste it into untrusted places"
      },
      {
        "title": "Performance",
        "body": "Use automationMode: AUTO_CREATE_PR for streamlined workflows\nOnly skip plan approval (requirePlanApproval: false) for routine, low-risk tasks in non-critical repos\nBreak complex tasks into smaller sessions"
      },
      {
        "title": "Extracting Results",
        "body": "When a session completes, retrieve the PR URL from outputs:\n\n# Get session details\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\" \\\n  | jq '.outputs[].pullRequest.url'"
      },
      {
        "title": "Known Limitations",
        "body": "Alpha API: Specifications may change; API keys and definitions are experimental\nNo long-running commands: Jules cannot run npm run dev or similar watch scripts\nContext size: Files > 768,000 tokens may be skipped\nPrompt sensitivity: Vague prompts may produce unexpected results"
      },
      {
        "title": "References",
        "body": "Jules API Documentation\nSessions Reference\nActivities Reference\nSources Reference\nTypes Reference\nGoogle Developers - Jules API\nJules Settings (API Keys)"
      }
    ],
    "body": "Jules REST API Skill\nQuick Start\n# 0. Set your API key (required — get one at https://jules.google.com/settings#api)\nexport JULES_API_KEY=\"your-api-key-here\"\n\n# 1. Verify available sources (pre-flight check)\n./scripts/jules_api.sh sources\n\n# 2. Create a session with plan approval and auto PR creation\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/OWNER/REPO\" \\\n  --title \"Add unit tests\" \\\n  --prompt \"Add comprehensive unit tests for the authentication module\" \\\n  --branch main \\\n  --require-plan-approval \\\n  --auto-pr\n\n# 3. Monitor session progress and approve the plan\n./scripts/jules_api.sh activities --session SESSION_ID\n./scripts/jules_api.sh approve-plan --session SESSION_ID\n\n\nNote: Use your GitHub username/org, not your local system username (e.g., sources/github/octocat/Hello-World, not sources/github/$USER/Hello-World).\n\nOverview\n\nThis skill enables programmatic interaction with the Jules REST API (v1alpha) for delegating coding tasks to Jules, Google's autonomous AI coding agent. It supports:\n\nTask Assignment: Create new coding sessions with specific prompts\nSession Monitoring: Track session state and activities in real-time\nPlan Management: Approve or review generated plans\nMessaging: Send follow-up messages to active sessions\nResult Integration: Retrieve PR URLs and code changes from completed sessions\nBefore You Start\n1. Get an API Key\n\nCreate a Jules API key in the Jules web app:\n\nNavigate to: https://jules.google.com/settings#api\nYou can have at most 3 API keys at a time\n\nExport it on the machine running the agent:\n\nexport JULES_API_KEY=\"your-api-key-here\"\n\n2. Connect Your GitHub Repository\n\nBefore the API can operate on a GitHub repo, you must:\n\nInstall the Jules GitHub app via the Jules web UI\nGrant access to the specific repositories you want Jules to work on\n3. Verify Repository Access\n# List available sources to verify access and see correct format\n./scripts/jules_api.sh sources\n\n\nYou'll see entries like:\n\n{\n  \"sources\": [\n    {\n      \"name\": \"sources/github/octocat/Hello-World\",\n      \"githubRepo\": {\n        \"owner\": \"octocat\",\n        \"repo\": \"Hello-World\",\n        \"defaultBranch\": { \"displayName\": \"main\" },\n        \"branches\": [\n          { \"displayName\": \"main\" },\n          { \"displayName\": \"develop\" }\n        ]\n      }\n    }\n  ]\n}\n\nBase URL & Authentication\nProperty\tValue\nBase URL\thttps://jules.googleapis.com/v1alpha\nAuth Header\tx-goog-api-key: $JULES_API_KEY\n\nAll requests authenticate with:\n\n-H \"x-goog-api-key: $JULES_API_KEY\"\n\nCore Concepts\nResources\nResource\tDescription\nSource\tA GitHub repository connected to Jules. Format: sources/github/{owner}/{repo}\nSession\tA unit of work where Jules executes a coding task. Contains state, activities, and outputs\nActivity\tAn individual event within a session (plan generated, message sent, progress update, etc.)\nSession States\nState\tDescription\nQUEUED\tSession is waiting to start\nPLANNING\tGenerating execution plan\nAWAITING_PLAN_APPROVAL\tWaiting for user to approve plan\nAWAITING_USER_FEEDBACK\tNeeds user input to continue\nIN_PROGRESS\tActively executing the task\nPAUSED\tTemporarily stopped\nCOMPLETED\tSuccessfully finished\nFAILED\tEncountered an error\nActivity Types\nType\tDescription\nPlan Generated\tA plan was generated for the task\nPlan Approved\tThe plan was approved (manually or auto)\nUser Message\tUser posted a message to the session\nAgent Message\tJules posted a message\nProgress Update\tStatus update on current work\nSession Completed\tSession finished successfully\nSession Failed\tSession encountered an error\nWorkflows\nOption 1: Session with Plan Approval and Auto-PR (Recommended)\n\nCreate a session that requires plan approval before execution and automatically creates a PR when complete:\n\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Fix login bug\" \\\n  --prompt \"Fix the null pointer exception in the login handler when email is empty\" \\\n  --branch main \\\n  --require-plan-approval \\\n  --auto-pr\n\n\nWhy this is recommended:\n\nYou review and approve the plan before Jules executes changes\nPR is created automatically on completion\nBalances automation with human oversight\nOption 2: Fully Automated Session (No Plan Approval)\n\nFor low-risk or routine tasks in non-sensitive repos, you can skip plan approval:\n\n# Create session without plan approval (use only for low-risk tasks)\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Fix typo in README\" \\\n  --prompt \"Fix the typo in README.md line 5\" \\\n  --branch main \\\n  --auto-pr\n\n\nWarning: Without --require-plan-approval, Jules will automatically approve its own plan and execute changes. Only use this for low-risk tasks in non-critical repos.\n\nOption 3: Interactive Session\n\nSend follow-up messages during an active session:\n\n# Create session\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/octocat/Hello-World\" \\\n  --title \"Add API endpoints\" \\\n  --prompt \"Add REST API endpoints for user management\" \\\n  --branch main\n\n# Send additional instructions\n./scripts/jules_api.sh send-message \\\n  --session SESSION_ID \\\n  --prompt \"Also add input validation for all endpoints\"\n\nAPI Reference\nSources\nList Sources\n\nLists all connected GitHub repositories.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sources\"\n\n\nQuery Parameters:\n\nParameter\tType\tDefault\tDescription\npageSize\tinteger\t30\tNumber of sources to return (1-100)\npageToken\tstring\t-\tToken from previous response for pagination\nfilter\tstring\t-\tAIP-160 filter (e.g., name=sources/source1)\n\nResponse:\n\n{\n  \"sources\": [\n    {\n      \"name\": \"sources/github/octocat/Hello-World\",\n      \"githubRepo\": {\n        \"owner\": \"octocat\",\n        \"repo\": \"Hello-World\",\n        \"isPrivate\": false,\n        \"defaultBranch\": { \"displayName\": \"main\" },\n        \"branches\": [\n          { \"displayName\": \"main\" },\n          { \"displayName\": \"develop\" }\n        ]\n      }\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n\nGet Source\n\nRetrieves a single source by name.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sources/github/octocat/Hello-World\"\n\n\nUse this to see available branches before creating a session.\n\nSessions\nCreate Session\n\nCreates a new coding session.\n\ncurl -sS \"https://jules.googleapis.com/v1alpha/sessions\" \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  -d '{\n    \"prompt\": \"Add unit tests for the login module\",\n    \"title\": \"Add Login Tests\",\n    \"sourceContext\": {\n      \"source\": \"sources/github/octocat/Hello-World\",\n      \"githubRepoContext\": {\n        \"startingBranch\": \"main\"\n      }\n    },\n    \"requirePlanApproval\": true,\n    \"automationMode\": \"AUTO_CREATE_PR\"\n  }'\n\n\nRequest Body Fields:\n\nField\tType\tRequired\tDescription\nprompt\tstring\tYes\tThe task description for Jules\ntitle\tstring\tNo\tShort title for the session\nsourceContext.source\tstring\tYes\tSource name (e.g., sources/github/owner/repo)\nsourceContext.githubRepoContext.startingBranch\tstring\tYes\tBranch to start from\nrequirePlanApproval\tboolean\tNo\tIf true, pause for plan approval. Recommended: true for production repos\nautomationMode\tstring\tNo\tSet to AUTO_CREATE_PR for automatic PR creation\n\nResponse:\n\n{\n  \"name\": \"sessions/31415926535897932384\",\n  \"id\": \"31415926535897932384\",\n  \"prompt\": \"Add unit tests for the login module\",\n  \"title\": \"Add Login Tests\",\n  \"state\": \"QUEUED\",\n  \"url\": \"https://jules.google/session/31415926535897932384\",\n  \"createTime\": \"2026-01-15T10:30:00Z\",\n  \"updateTime\": \"2026-01-15T10:30:00Z\"\n}\n\nList Sessions\n\nLists your sessions.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions?pageSize=20\"\n\n\nQuery Parameters:\n\nParameter\tType\tDefault\tDescription\npageSize\tinteger\t30\tNumber of sessions to return (1-100)\npageToken\tstring\t-\tToken from previous response for pagination\nGet Session\n\nRetrieves a single session by ID.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\"\n\n\nResponse includes outputs on completion:\n\n{\n  \"name\": \"sessions/31415926535897932384\",\n  \"id\": \"31415926535897932384\",\n  \"state\": \"COMPLETED\",\n  \"outputs\": [\n    {\n      \"pullRequest\": {\n        \"url\": \"https://github.com/octocat/Hello-World/pull/42\",\n        \"title\": \"Add Login Tests\",\n        \"description\": \"This PR adds comprehensive unit tests...\"\n      }\n    }\n  ]\n}\n\nSend Message\n\nSends a message to an active session.\n\ncurl -sS \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage\" \\\n  -d '{\"prompt\": \"Also add integration tests\"}'\n\n\nUse this to provide feedback, answer questions, or give additional instructions.\n\nApprove Plan\n\nApproves a pending plan (only needed if requirePlanApproval was true).\n\ncurl -sS \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan\"\n\nDelete Session\n\nDeletes a session.\n\ncurl -sS \\\n  -X DELETE \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\"\n\nActivities\nList Activities\n\nLists activities for a session.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=30\"\n\n\nQuery Parameters:\n\nParameter\tType\tDefault\tDescription\npageSize\tinteger\t50\tNumber of activities to return (1-100)\npageToken\tstring\t-\tToken from previous response for pagination\n\nResponse:\n\n{\n  \"activities\": [\n    {\n      \"name\": \"sessions/123/activities/456\",\n      \"createTime\": \"2026-01-15T10:31:00Z\",\n      \"planGenerated\": {\n        \"plan\": \"1. Analyze existing code\\n2. Create test files\\n3. Write tests...\"\n      }\n    },\n    {\n      \"name\": \"sessions/123/activities/457\",\n      \"createTime\": \"2026-01-15T10:32:00Z\",\n      \"progressUpdate\": {\n        \"title\": \"Writing tests\",\n        \"details\": \"Creating test file for auth module...\"\n      }\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n\n\nActivities may include artifacts with code changes:\n\n{\n  \"artifacts\": [\n    {\n      \"changeSet\": {\n        \"gitPatch\": {\n          \"unidiffPatch\": \"diff --git a/...\",\n          \"baseCommitId\": \"abc123\",\n          \"suggestedCommitMessage\": \"Add unit tests for login\"\n        }\n      }\n    }\n  ]\n}\n\nGet Activity\n\nRetrieves a single activity by ID.\n\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities/ACTIVITY_ID\"\n\nScript Reference\njules_api.sh\n\nThe scripts/jules_api.sh script provides a convenient wrapper for common API operations.\n\nUsage:\n\n# List sources\n./scripts/jules_api.sh sources\n\n# List sessions\n./scripts/jules_api.sh sessions [--page-size N]\n\n# List activities for a session\n./scripts/jules_api.sh activities --session <id> [--page-size N]\n\n# Send message to session\n./scripts/jules_api.sh send-message --session <id> --prompt \"...\"\n\n# Approve plan\n./scripts/jules_api.sh approve-plan --session <id>\n\n# Create new session\n./scripts/jules_api.sh new-session \\\n  --source \"sources/github/owner/repo\" \\\n  --title \"...\" \\\n  --prompt \"...\" \\\n  [--branch main] \\\n  [--auto-pr] \\\n  [--no-plan-approval]\n\n\nFlags:\n\nFlag\tDescription\n--source\tSource name (format: sources/github/owner/repo)\n--title\tSession title\n--prompt\tTask description or message content\n--session\tSession ID\n--branch\tStarting branch (default: main)\n--auto-pr\tEnable automatic PR creation\n--require-plan-approval\tRequire explicit plan approval (default)\n--no-plan-approval\tSkip plan approval (use for low-risk tasks only)\n--page-size\tNumber of results to return\njules.js\n\nThe scripts/jules.js script wraps the Jules CLI for programmatic use.\n\nUsage:\n\nnode scripts/jules.js version\nnode scripts/jules.js list-repos\nnode scripts/jules.js list-sessions\nnode scripts/jules.js new --repo owner/repo --task \"Your task\"\nnode scripts/jules.js pull --session SESSION_ID\n\nCommon Error Patterns\n\"Source not found\" or \"Repository not found\"\n\nCause: Repository not connected or incorrect source name format.\n\nSolution:\n\nRun ./scripts/jules_api.sh sources to list available sources\nEnsure you've installed the Jules GitHub app for this repo\nUse the exact source name from the list (e.g., sources/github/octocat/Hello-World)\n\"Missing JULES_API_KEY\"\n\nCause: API key not set in environment.\n\nSolution:\n\nexport JULES_API_KEY=\"your-api-key\"\n\nAuthentication Errors\n\nCause: Invalid or expired API key.\n\nSolution:\n\nGenerate a new API key at https://jules.google.com/settings#api\nUpdate the JULES_API_KEY environment variable\nNote: You can have at most 3 API keys at a time\nSession Stuck in AWAITING_PLAN_APPROVAL\n\nCause: Session was created with requirePlanApproval: true.\n\nSolution:\n\n./scripts/jules_api.sh approve-plan --session SESSION_ID\n\nTask Fails with Vague Error\n\nCause: Vague prompts may produce unexpected results.\n\nSolution:\n\nWrite clear, specific prompts\nBreak large tasks into smaller, focused tasks\nAvoid prompts that require long-running commands (dev servers, watch scripts)\nLarge Files Skipped\n\nCause: Files exceeding 768,000 tokens may be skipped.\n\nSolution:\n\nBreak down operations on very large files\nConsider splitting large files before processing\nBest Practices\nWriting Effective Prompts\nBe specific: Instead of \"fix the bug\", say \"fix the null pointer exception in auth.js:45 when email is undefined\"\nProvide context: Mention relevant files, functions, or error messages\nKeep tasks focused: One logical task per session\nMonitoring Sessions\nPoll session state to track progress\nCheck activities for detailed progress updates\nHandle AWAITING_USER_FEEDBACK state by sending clarifying messages\nSecurity\nNever include secrets or credentials in prompts\nReview generated PRs before merging\nUse requirePlanApproval: true (recommended for all repos, especially production)\nOnly install the Jules GitHub app on repositories you intend to use with Jules — limit access scope\nTreat JULES_API_KEY as a secret: store it securely, rotate it regularly, and never paste it into untrusted places\nPerformance\nUse automationMode: AUTO_CREATE_PR for streamlined workflows\nOnly skip plan approval (requirePlanApproval: false) for routine, low-risk tasks in non-critical repos\nBreak complex tasks into smaller sessions\nExtracting Results\n\nWhen a session completes, retrieve the PR URL from outputs:\n\n# Get session details\ncurl -sS \\\n  -H \"x-goog-api-key: $JULES_API_KEY\" \\\n  \"https://jules.googleapis.com/v1alpha/sessions/SESSION_ID\" \\\n  | jq '.outputs[].pullRequest.url'\n\nKnown Limitations\nAlpha API: Specifications may change; API keys and definitions are experimental\nNo long-running commands: Jules cannot run npm run dev or similar watch scripts\nContext size: Files > 768,000 tokens may be skipped\nPrompt sensitivity: Vague prompts may produce unexpected results\nReferences\nJules API Documentation\nSessions Reference\nActivities Reference\nSources Reference\nTypes Reference\nGoogle Developers - Jules API\nJules Settings (API Keys)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/SanJacob99/jules-and-lobster",
    "publisherUrl": "https://clawhub.ai/SanJacob99/jules-and-lobster",
    "owner": "SanJacob99",
    "version": "1.0.5",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/jules-and-lobster",
    "downloadUrl": "https://openagent3.xyz/downloads/jules-and-lobster",
    "agentUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent",
    "manifestUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/jules-and-lobster/agent.md"
  }
}