jules

Delegate coding tasks to Google's Jules AI agent on GitHub repositories.

Environment Variables

Variable	Required	Description
JULES_API_KEY	For API auth	API key from jules.google.com/settings

Setup (Run Before First Command)

Two auth paths are available. Use Path 1 for interactive use, Path 2 for headless/agent use.

Path 1: CLI (Interactive)

1. Install CLI

which jules || npm install -g @google/jules

2. Check Auth

jules remote list --repo

If fails → tell user to run jules login (or --no-launch-browser for headless)

Path 2: API Key (Headless / Agent Use)

1. Get API Key

Get key from jules.google.com/settings (3-key limit per account).

2. Set Environment Variable

export JULES_API_KEY="your-api-key"

3. Verify

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=1" | head -20

Common Setup (Both Paths)

Auto-Detect Repo

git remote get-url origin 2>/dev/null | sed -E 's#.*(github\.com)[/:]([^/]+/[^/.]+)(\.git)?#\2#'

If not GitHub or not in git repo → ask user for --repo owner/repo

Verify Repo Connected

Check repo is in jules remote list --repo. If not → direct to https://jules.google.com

Commands (CLI)

Create Tasks

jules new "Fix auth bug"                                   # Auto-detected repo
jules new --repo owner/repo "Add unit tests"               # Specific repo
jules new --repo owner/repo --parallel 3 "Implement X"     # Parallel sessions
cat task.md | jules new --repo owner/repo                  # From stdin

Monitor

jules remote list --session    # All sessions
jules remote list --repo       # Connected repos

Retrieve Results

jules remote pull --session <id>         # View diff
jules remote pull --session <id> --apply # Apply locally
jules teleport <id>                      # Clone + apply

Latest Session Shortcut

LATEST=$(jules remote list --session 2>/dev/null | awk 'NR==2 {print $1}')
jules remote pull --session $LATEST

Commands (API)

Create a Task

curl -s -X POST "https://jules.googleapis.com/v1alpha/sessions" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix auth bug",
    "prompt": "Fix the authentication timeout issue in src/auth.ts",
    "sourceContext": {
      "repository": "owner/repo",
      "branchName": "main"
    },
    "automationMode": "AUTO_CREATE_PR",
    "requirePlanApproval": false
  }'

Key fields:

• prompt — The task description (required)
• sourceContext.repository — GitHub owner/repo (required)
• sourceContext.branchName — Target branch (default: repo default)
• automationMode — "AUTO_CREATE_PR" to auto-create PRs, omit for manual
• title — Display name for the session
• requirePlanApproval — true to pause for plan review before execution

List Sessions

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10"

Get Session Status

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

Poll Until Complete (API)

SESSION_ID="<id>"
while true; do
  STATE=$(curl -s -H "x-goog-api-key: $JULES_API_KEY" \
    "https://jules.googleapis.com/v1alpha/sessions/$SESSION_ID" \
    | python3 -c "import sys,json; print(json.load(sys.stdin).get('state','UNKNOWN'))")
  case "$STATE" in
    COMPLETED)
      echo "Done!"
      break ;;
    FAILED)
      echo "Failed. Check: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *)
      echo "State: $STATE - waiting 30s..."
      sleep 30 ;;
  esac
done

Smart Context Injection

Enrich prompts with current context for better results:

BRANCH=$(git branch --show-current)
RECENT_FILES=$(git diff --name-only HEAD~3 2>/dev/null | head -10 | tr '\n' ', ')
RECENT_COMMITS=$(git log --oneline -5 | tr '\n' '; ')
STAGED=$(git diff --cached --name-only | tr '\n' ', ')

Use when creating tasks (CLI):

jules new --repo owner/repo "Fix the bug in auth module. Context: branch=$BRANCH, recently modified: $RECENT_FILES"

Use when creating tasks (API):

curl -s -X POST "https://jules.googleapis.com/v1alpha/sessions" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"Fix the bug in auth module. Context: branch=$BRANCH, recently modified: $RECENT_FILES\",
    \"sourceContext\": {\"repository\": \"owner/repo\", \"branchName\": \"$BRANCH\"},
    \"automationMode\": \"AUTO_CREATE_PR\"
  }"

Template Prompts

Quick commands for common tasks:

Add Tests

FILES=$(git diff --name-only HEAD~3 2>/dev/null | grep -E '\.(js|ts|py|go|java)$' | head -5 | tr '\n' ', ')
jules new "Add unit tests for recently modified files: $FILES. Include edge cases and mocks where needed."

Add Documentation

FILES=$(git diff --name-only HEAD~3 2>/dev/null | grep -E '\.(js|ts|py|go|java)$' | head -5 | tr '\n' ', ')
jules new "Add documentation comments to: $FILES. Include function descriptions, parameters, return values, and examples."

Fix Lint Errors

jules new "Fix all linting errors in the codebase. Run the linter, identify issues, and fix them while maintaining code functionality."

Review PR

PR_NUM=123
PR_INFO=$(gh pr view $PR_NUM --json title,body,files --jq '"\(.title)\n\(.body)\nFiles: \(.files[].path)"')
jules new "Review this PR for bugs, security issues, and improvements: $PR_INFO"

Git Integration (Apply + Commit)

After Jules completes, apply changes to a new branch:

SESSION_ID="<id>"
TASK_DESC="<brief description>"

# Create branch, apply, commit
git checkout -b "jules/$SESSION_ID"
jules remote pull --session "$SESSION_ID" --apply
git add -A
git commit -m "feat: $TASK_DESC

Jules session: $SESSION_ID"

# Optional: push and create PR
git push -u origin "jules/$SESSION_ID"
gh pr create --title "$TASK_DESC" --body "Automated changes from Jules session $SESSION_ID"

Poll Until Complete (CLI)

Wait for session to finish:

SESSION_ID="<id>"
while true; do
  STATUS=$(jules remote list --session 2>/dev/null | grep "$SESSION_ID" | awk '{print $NF}')
  case "$STATUS" in
    Completed)
      echo "Done!"
      jules remote pull --session "$SESSION_ID"
      break ;;
    Failed)
      echo "Failed. Check: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *User*)
      echo "Needs input: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *)
      echo "Status: $STATUS - waiting 30s..."
      sleep 30 ;;
  esac
done

AGENTS.md Template

Create in repo root to improve Jules results:

# AGENTS.md

## Project Overview
[Brief description]

## Tech Stack
- Language: [TypeScript/Python/Go/etc.]
- Framework: [React/FastAPI/Gin/etc.]
- Testing: [Jest/pytest/go test/etc.]

## Code Conventions
- [Linter/formatter used]
- [Naming conventions]
- [File organization]

## Testing Requirements
- Unit tests for new features
- Integration tests for APIs
- Coverage target: [X]%

## Build & Deploy
- Build: `[command]`
- Test: `[command]`

Session States

Status	Action
Planning / In Progress	Wait
Awaiting User F	Respond at web UI
Completed	Pull results
Failed	Check web UI

Notes

• No CLI reply → Use web UI for Jules questions
• No CLI cancel → Use web UI to cancel
• GitHub only → GitLab/Bitbucket not supported
• AGENTS.md → Jules reads from repo root for context
• API vs CLI → Use API (JULES_API_KEY) for headless/agent automation; use CLI for interactive sessions