jules-cli

name	jules-cli
description	Interact with the Jules CLI to manage asynchronous coding sessions. Use this skill sparingly for complex, isolated tasks that benefit from a remote VM.

Jules CLI Skill

Overview

This skill enables the agent to interact with the jules CLI. It supports task assignment, session monitoring, and result integration.

Usage Guidelines (CRITICAL)

To prevent excessive and inappropriate session creation, you must follow these rules:

1. Local First: If you can solve the task locally within your current environment (e.g., editing files, running tests, small refactors), do not use Jules.
2. Complexity Threshold: Only use Jules for tasks that are:
   • Large-scale: Touching many files or requiring significant architectural changes.
   • Isolated: Benefiting from a clean, remote environment to avoid local dependency issues.
   • Exploratory: Tasks where the solution isn't immediately obvious and requires iteration in a VM.
3. No Proliferation (One at a Time):
   • Never create multiple sessions for the same task.
   • Never use a loop or parallel execution to spin up several sessions at once.
   • Wait for a session to complete and inspect the results before deciding if another session is needed.
4. No "Small" Tasks: Do not submit tasks like "Add a comment", "Change a variable name", or "Fix a typo".

---

Safety Controls

• Approval Required: If you are unsure if a task is "complex enough" for Jules, ask the user for permission before running jules remote new.
• Verification: Always run jules remote list --session before creating a new one to ensure you don't already have a pending session for the same repository.

---

Core Workflow (Manual Control)

Prefer using the CLI directly to maintain situational awareness.

1. Pre-flight Check

Verify repository access and format.

jules remote list --repo

Note: Ensure the repo format is GITHUB_USERNAME/REPO.

2. Submit Task

Create a session and capture the Session ID.

# Capture the output to get the ID
jules remote new --repo <repo> --session "Detailed task description" < /dev/null

3. Monitor Progress

List sessions and look for your ID. Use this robust one-liner to check the status (it handles statuses with spaces like "In Progress"):

Check Status:

# Extract status for a specific ID by splitting on 2+ spaces
jules remote list --session | python3 -c "import sys, re; [print(re.split(r'\s{2,}', l.strip())[-1]) for l in sys.stdin if l.startswith('<SESSION_ID>')] "

4. Integrate Results

Once the status is Completed, pull and apply the changes.

jules remote pull --session <SESSION_ID> --apply < /dev/null

---

Error Handling & Troubleshooting

• Repository Not Found: Verify format with jules remote list --repo. It must match the GitHub path.
• TTY Errors: Always use < /dev/null for non-interactive automation with the raw jules command.
• Credentials: If you see login errors, ensure HOME is set correctly or run jules login.

---

Command Reference

Command	Purpose
jules remote list --repo	Verify available repositories and their exact names.
jules remote list --session	List active and past sessions to check status.
jules remote new	Create a new coding task.
jules remote pull	Apply changes from a completed session.
jules teleport <id>	Clone and apply changes (useful for fresh environments).