Jules CLI Skill

Quick Start

# 1. Verify available repos (pre-flight check)
jules remote list --repo

# 2. Submit a task and wait for completion
./scripts/jules_submit.py --repo GITHUB_USERNAME/REPO "Your task description"

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

---

Overview

This skill enables the agent to interact with the jules CLI. It supports task assignment, session monitoring, and result integration (pulling patches from completed sessions).

Before You Start

Verify Repository Access

Before submitting tasks, verify which repositories are available and confirm the correct format:

# List available repos to verify access and see correct username format
jules remote list --repo

Important: The --repo flag requires your GitHub username or organization name, not your local system username.

• Correct: octocat/Hello-World (GitHub username)
• Incorrect: localuser/Hello-World (local system username)

If you're unsure of your GitHub username:

1. Run jules remote list --repo to see available repos with correct formatting
2. Or check your GitHub profile at https://github.com/settings/profile

Core Capabilities

1. Automated Submission: Use jules_submit.py to handle the session lifecycle (new session → wait → pull → apply).
2. Task Assignment: Create new coding sessions with jules remote new.
3. Session Monitoring: List and parse remote sessions to track progress.
4. Result Integration: Pull and apply patches from completed sessions.

Workflows

Option 1: Automated Task Submission (Recommended)

Why this is recommended:

• Non-blocking: The script handles polling automatically, freeing up the terminal
• TTY-safe: Automatically handles TTY/input redirection issues common in automation
• All-in-one: Creates session, waits for completion, and applies changes locally
• Error handling: Built-in retry logic and prerequisite checks

The jules_submit.py script handles session creation, waiting for completion, and applying results.

# Submit task and wait for completion
./scripts/jules_submit.py --repo octocat/Hello-World "Implement unit tests for the login module"

# Submit without waiting (fire-and-forget)
./scripts/jules_submit.py --repo octocat/Hello-World --no-wait "Research API options"

Flags:

• --repo <repo>: Repository in GITHUB_USERNAME/REPO format (e.g., octocat/Hello-World)
• --no-wait: Exit immediately after creating session (don't wait for completion)

Option 2: Manual Workflow

Use this when you need granular control over each step or want to inspect intermediate results.

# Step 1: Create session
jules remote new --repo octocat/Hello-World --session "Task description"

# Step 2: Wait for session (check status until terminal state)
./scripts/wait_for_session.sh <SESSION_ID>

# Step 3: Pull and apply changes
jules remote pull --session <SESSION_ID> --apply

Common Error Patterns

"repo doesn't exist" or "repository not found"

Cause: Using local system username instead of GitHub username

Solution:

• Verify with jules remote list --repo to see correct format
• Use GitHub username: octocat/repo not localuser/repo

"Login Related" Errors

If you see Trying to make a GET request without a valid client (did you forget to login?) when running from automation:

1. Verify HOME: Ensure the HOME environment variable is set to the user's home directory.
2. Credentials: Ensure ~/.jules/cache/oauth_creds.json exists and is valid. Run jules login manually if needed.

TTY Errors

If you see could not open a new TTY or inappropriate ioctl for device:

1. Use redirected input: echo "task" | jules ... < /dev/null.
2. The provided scripts (jules_submit.py) handle this automatically.

Testing & Validation

This skill has been validated with live Jules sessions. Key test scenarios include:

• ✅ Session creation with various repository formats
• ✅ TTY-safe automation in non-interactive environments
• ✅ HOME environment variable edge cases
• ✅ Session status polling (Completed, Failed, Cancelled states)
• ✅ Patch application workflows

All error patterns documented above were discovered and resolved during live testing with the Jules platform.

Command Reference

Essential Commands

jules remote new

Assigns a new session to Jules in a remote VM.

jules remote new --repo octocat/Hello-World --session "Task description"

Flags:

• --repo <repo>: Repository in GITHUB_USERNAME/REPO format
• --session <task>: The task description (required)
• --parallel <num>: Number of parallel sessions (1-5)

jules remote list

Lists remote sessions or repositories.

# List your active sessions
jules remote list --session

# List available repos (useful for verifying repo format)
jules remote list --repo

jules remote pull

Pulls the result of a remote session and optionally applies it.

jules remote pull --session <SESSION_ID> --apply

Flags:

• --session <id>: The session ID (required)
• --apply: Apply the patch to the local repository

Resources

Scripts (in scripts/)

• jules_submit.py: Primary tool for automation. Wraps the entire workflow.
• parse_sessions.py: Parses the tabular output of jules remote list --session into JSON format.
• wait_for_session.sh: Polls a session status until it reaches a terminal state.

Full Reference

• references/usage.md: Comprehensive reference of all jules commands, flags, and advanced usage patterns.