jules-mcp: Instructions file for Codex

Jules MCP Orchestrator Mode

This document describes how to use the jules-mcp server in orchestrator mode where a local agent coordinates work with Jules as a remote coding assistant.

Overview

Jules is an advanced developer agent. Simply specify the task clearly and concisely - no need to provide code snippets or implementation details. Jules will analyze the codebase, plan the work, and execute it independently.

Orchestrator Workflow

When the local agent needs to delegate work to Jules, follow this sequential workflow:

1. Pull Latest Changes

Before creating any new Jules session, always pull the latest changes from the remote to ensure Jules works with up-to-date code:

git pull origin <branch>

2. Create Jules Session

Create a new Jules session for the task. Jules is autonomous - describe what needs to be done:

Required parameters:

• owner: GitHub repository owner (e.g., "MikBin")
• repo: Repository name (e.g., "jules-mcp")
• branch: Must be the default branch (main or master) - Jules automatically creates its own feature branch for each session
• prompt: Clear task description

Optional parameters:

• title: Session title for identification
• requirePlanApproval: Set to true if you want to review before execution (default: false for auto-approval)
• automationMode: Set to "AUTO_CREATE_PR" for automatic PR creation on completion

3. Monitor Session

Wait for the session to complete. Check session status periodically using the built-in jules_wait tool to conserve tokens:

• Use jules_wait to pause for configurable seconds between status checks (recommended: 300 seconds)
• For periodic polling, use jules_check_jules only (compact Q/C/F/N response)
• If state is AWAITING_PLAN_APPROVAL, approve the plan
• If state is AWAITING_USER_FEEDBACK, respond using jules_send_message to provide clarification or additional instructions
• If state is IN_PROGRESS, continue monitoring (sleep then check again)
• If state is COMPLETED or FAILED, proceed to next step