🤖 Google Jules Workflow Optimizer

Google Jules is a free* AI coding agent but it has some quirks that make development very slow. These are the scripts I use to speed up my workflow.

A comprehensive suite of TypeScript scripts designed to streamline AI-powered development workflows, specifically optimized for Google Jules (AI coding agent) integration with GitHub Copilot, Linear project management, and modern development practices.

🎯 Why These Scripts?

Google Jules is powerful but has workflow friction points:

Context Switching: Constantly switching between Linear issues, GitHub PRs, and code reviews
Manual Copy-Paste: Repeatedly copying branch names, PR discussions, and issue context
Review Overhead: Managing the Jules → Copilot → Jules feedback loop manually

⚡ Quick Installation

Option 1: Global Installation (Recommended)

Install globally for system-wide access:

npm install -g @ihildy/google-jules-workflow

Then use commands directly:

jules-pr --help
jules-pr-manager
jules-extract-pr

Option 2: One-time Usage

Run commands without installing:

npx @ihildy/google-jules-workflow jules-pr
npx @ihildy/google-jules-workflow jules-pr-manager

Option 3: Project Installation

Install in your project:

npm install @ihildy/google-jules-workflow
# or
pnpm add @ihildy/google-jules-workflow
# or
yarn add @ihildy/google-jules-workflow

Then use via npm scripts or npx:

npx jules-pr --help
# or add to your package.json scripts

📦 Manual Installation (Development)

For development or customization:

Clone the repository

git clone https://github.com/iHildy/google-jules-workflow.git
cd google-jules-workflow

Install dependencies

pnpm install
# or npm install / yarn install

Authenticate GitHub CLI (if not done)
```
gh auth login
```
Test the setup
```
pnpm run pr-manager --help
```

Optional: Link globally for development

npm link
# Now you can use jules-pr anywhere

📚 Quick Command Reference

🔧 Unified Commands (jules-pr)

Discussion Extraction:

jules-pr - Auto-detect current branch and extract unified PR/issue discussion for providing changes to jules
jules-pr --jules - Jules mode: copy branch name first, then full discussion
jules-pr --summary - Extract with AI-powered summary and insights
jules-pr --jules --summary - Combined Jules mode + AI summary
jules-pr <number|ID> - Extract specific GitHub PR or Linear issue

Workflow Management:

jules-pr summary - Overview of PRs needing attention (default)
jules-pr list-needing-review - PRs where Jules committed but Copilot hasn't reviewed
jules-pr list-needing-update - PRs where Copilot reviewed but Jules hasn't addressed feedback
jules-pr list-linear-issues - Linear issues without PRs ready for development
jules-pr assign-copilot - Auto-assign GitHub Copilot to PRs where Jules made commits

Configuration:

jules-config-init - Create customizable configuration file
jules-config-init --force - Overwrite existing configuration file

🛠️ Alternative Usage (npm scripts)

If you installed the package in your project, you can also use these scripts:

npm run pr - Same as jules-pr
npm run pr-jules - Same as jules-pr --jules
npm run pr-summary - Same as jules-pr --summary
npm run pr-js - Same as jules-pr --jules --summary
npm run pr-manager - Same as jules-pr summary

🚀 Optimal Workflow Guide

Complete Task Flow (Start to Finish)

Step 1: Find Work

Find issues ready for development

jules-pr list-linear-issues

Select issue → Provide context to Jules

Step 2: Development (once Jules is done and branch is published)

Request Copilot review for Jules to act on later.

jules-pr assign-copilot

Step 3: Address Review

Get PRs that have been reviewed by Copilot but not updated by Jules, provide the output to Jules to update the branch

jules-pr list-needing-update

Step 4: Status Check

jules-pr summary # Check overall workflow status

Step 5: Continue or Complete

If more feedback: Repeat Step 3

If approved: Task complete, return to Step 1

🎭 Jules Mode Workflow

Jules Mode is specifically designed for AI coding agents:

jules-pr --jules

Step 1: Copies branch name (e.g., feature/GRE-213-disable-donations-toggle) for the task input in Jules

Step 2: After Enter press, copies full discussion with context to provide to Jules

Perfect for Jules because:

Branch name sets proper context (updates branch if it is the exact same when you press "Publish Branch")
Full discussion provides comprehensive feedback
Automatic priority classification helps focus on critical items

⚡ Quick Context Switching

# Currently working on PR, need context
jules-pr # Auto-detect current branch

# Need to review specific issue
jules-pr GRE-456 # Extract Linear issue + find GitHub PR

# Need to review specific PR
jules-pr 123 # Extract GitHub PR + find Linear issue

📊 Batch Processing

# Process all PRs needing attention
jules-pr list-needing-update
# Choose 'j' for each PR to run Jules mode automatically

# Start multiple new features
jules-pr list-linear-issues
# Choose 'j' for each issue to extract context

⚙️ Setup Guide

Prerequisites

Node.js 18+ (with npm, pnpm, or yarn)
GitHub CLI (gh) installed and authenticated
Linear account with API access (optional but highly recommended)
Google Jules or similar AI coding agent

Quick Setup

Install the package globally

npm install -g @ihildy/google-jules-workflow

Authenticate GitHub CLI (if not done)
```
gh auth login
```
Test the installation
```
jules-pr --help
```
Create configuration file (optional but recommended)
```
jules-config-init
```
This creates a jules-workflow.config.js file that you can customize to match your preferences.
Recommended: Configure environment variables (see below)

Environment Configuration

Create a .env file in your project root or set environment variables:

# Required for Linear integration (highly recommended)
LINEAR_API_KEY=your_linear_api_key_here

# Required for AI summaries (optional but useful)
GEMINI_API_KEY=your_gemini_api_key_here

Getting API Keys:

Linear API Key: Linear Settings → API → Personal API Keys
Gemini API Key: Google AI Studio → Get API Key

Package.json Integration (Optional)

If you want to add these to your project's package.json scripts:

{
  "scripts": {
    "pr": "jules-pr",
    "pr-jules": "jules-pr --jules",
    "pr-summary": "jules-pr --summary",
    "pr-js": "jules-pr --jules --summary",
    "pr-manager": "jules-pr summary",
    "pr-assign-copilot": "jules-pr assign-copilot",
    "pr-list-needing-review": "jules-pr list-needing-review",
    "pr-list-needing-update": "jules-pr list-needing-update",
    "pr-list-linear-issues": "jules-pr list-linear-issues"
  }
}

✨ Key Features

🔗 Unified Context Extraction

Smart Linking: Automatically connects Linear issues with GitHub PRs
Branch Intelligence: Parses branch names to find related items
Interactive Fallback: Prompts when auto-detection fails

🤖 AI-Optimized Workflows

Jules Mode: Two-step clipboard copying optimized for AI agents (like Jules's UI)
Gemini Summaries: AI-powered analysis with actionable insights
Smart Prioritization: Automatic classification of feedback importance
Debug Output: Shows exactly what's being copied to clipboard

📊 Workflow Automation

Review Assignment: Automatic Copilot reviewer assignment
Status Tracking: Monitor Jules → Copilot → Jules feedback loops
Priority Sorting: Linear urgency-based ordering
Interactive Processing: Batch operations with user control

🎯 Developer Experience

Auto-Detection: Context-aware branch and repository analysis
Parallel Processing: Fast data fetching from multiple APIs
Error Handling: Comprehensive logging and fallback behavior
Clean Output: Reduced noise, focused on actionable information

⚙️ Customization

Jules Workflow can be customized to match your preferences and project needs. After installation, run:

jules-config-init

This creates a jules-workflow.config.js file with extensive options. Here are some key customizations:

Jules Mode Behavior

module.exports = {
  julesMode: {
    // What to copy first in Jules mode
    firstCopy: "branch_name", // Options: "branch_name", "linear_id", "title"

    // Custom prompts for the two-step process
    prompts: {
      firstCopyComplete: "✨ Press Enter to copy full discussion...",
      secondCopyComplete: "📋 Full context copied!",
    },
  },
};

Priority Keywords

Customize how comments are classified by priority:

module.exports = {
  priority: {
    customKeywords: {
      HIGH: ["deployment", "production", "security"],
      MEDIUM: ["documentation", "testing", "refactor"],
      LOW: ["cleanup", "style", "typo"],
    },
  },
};

Output Formatting

Control what sections appear and in what order:

module.exports = {
  output: {
    // Include/exclude sections
    includeJulesRules: true,
    includeBotFeedback: true,

    // Customize section order
    sectionOrder: [
      "header",
      "summaryHeader",
      "humanReviews",
      "actionItems",
      "julesRules",
    ],
  },
};

Workflow Preferences

module.exports = {
  workflow: {
    // Prefer Linear issues over PRs when auto-detecting
    autoDetectPreference: "linear", // Options: "linear", "pr"

    // Auto-save all extractions
    autoSave: {
      enabled: true,
      directory: "./jules-extractions",
    },
  },
};

💡 Tip: The configuration file contains extensive comments explaining every option. Edit it to match your workflow preferences.

🔧 Advanced Usage

Custom Aliases

Add these to your shell profile (.zshrc, .bashrc):

# Unified jules-pr commands (recommended)
alias pr="jules-pr"
alias prj="jules-pr --jules"  # Jules mode
alias prs="jules-pr --summary"  # AI summary
alias prjs="jules-pr --jules --summary"  # Jules + Summary
alias prm="jules-pr summary"  # Workflow status
alias pru="jules-pr list-needing-update"  # PRs needing Jules update
alias prl="jules-pr list-linear-issues"  # Linear issues ready for Jules

# Alternative using npx (if not globally installed)
alias pr="npx @ihildy/google-jules-workflow jules-pr"
alias prm="npx @ihildy/google-jules-workflow jules-pr summary"

Integration with Other Tools

VSCode Tasks (.vscode/tasks.json):

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "PR Context",
      "type": "shell",
      "command": "jules-pr",
      "args": ["--jules"],
      "group": "build"
    },
    {
      "label": "PR Workflow Status",
      "type": "shell",
      "command": "jules-pr",
      "args": ["summary"],
      "group": "build"
    },
    {
      "label": "PRs Needing Update",
      "type": "shell",
      "command": "jules-pr",
      "args": ["list-needing-update"],
      "group": "build"
    }
  ]
}

Git Hooks (.git/hooks/post-checkout):

#!/bin/sh
jules-pr 2>/dev/null || true

GitHub Actions (.github/workflows/pr-automation.yml):

name: PR Automation
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  assign-copilot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "18"
      - run: npx @ihildy/google-jules-workflow jules-pr assign-copilot
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

📊 Priority Classification System

Comments are automatically classified using intelligent keyword detection:

🚨 HIGH: security, breaking, critical, urgent, error, fail, bug, broken
⚠️ MEDIUM: performance, optimization, refactor, improvement, consider, should
ℹ️ LOW: nitpick, style, formatting, typo, minor, suggestion

🤖 Supported Integrations

GitHub

Pull requests, reviews, comments, commits
Automatic Copilot reviewer assignment
Bot detection and filtering

Linear

Issues, priorities, labels, attachments
Branch name parsing for issue linking
Priority-based sorting

AI Models

Google Gemini for summaries and analysis
Extensible for other AI providers

🔍 Auto-Detection Logic

Branch Analysis: Extracts Linear IDs (e.g., GRE-123) from branch names like feature/GRE-123-description
PR Linking: Finds PRs associated with Linear issue branches
Attachment Scanning: Discovers GitHub links in Linear issue attachments
Fallback Prompting: Interactive input when auto-detection fails

🚀 Performance Features

Parallel API Calls: Reviews, comments, and PR details fetched simultaneously
Smart Caching: Avoids redundant API calls within sessions
Processing Time Tracking: Shows execution time for optimization
Optimized Output: Truncates verbose code contexts for readability
Clean Logging: Reduced verbose output, focused on actionable information

🐛 Troubleshooting

Common Issues

Command not found: jules-pr

Ensure you installed globally: npm install -g @ihildy/google-jules-workflow
Or use npx: npx @ihildy/google-jules-workflow jules-pr
Check your PATH includes npm global binaries: npm bin -g

Clipboard not working:

Check terminal output for "📋 CONTENT BEING COPIED TO CLIPBOARD" section
Verify clipboard permissions on macOS
Try manual copy from debug output

GitHub API errors:

Ensure gh auth login is completed
Check repository permissions
Verify GitHub CLI version (gh --version)

Linear API issues:

Verify LINEAR_API_KEY in .env file
Check Linear API key permissions
Ensure team/workspace access

Permission errors on execution:

The scripts should be executable by default, but if you encounter issues:
```
chmod +x ./node_modules/@ihildy/google-jules-workflow/scripts/*.ts
```

Configuration warnings:

If you see "⚠️ No configuration file found!" warnings, run jules-config-init to create a config file
This warning is informational - the tools work fine with default settings
Customize the generated config file to match your workflow preferences

Debug Mode

# Enable detailed logging
jules-pr 123 --debug

# Save output for inspection
jules-pr 123 --save debug-output.md

# Test specific workflow components
jules-pr summary --verbose
jules-pr list-needing-review

🎯 Best Practices

Install Globally: npm install -g @ihildy/google-jules-workflow for best experience
Configure Your Workflow: Run jules-config-init and customize settings to match your preferences
Start with Auto-Detection: jules-pr works for most cases
Use Jules Mode for AI Sessions: jules-pr --jules for streamlined workflows
Daily Workflow Checks: jules-pr summary for status overview
Address Reviews Promptly: jules-pr list-needing-update before new work
Save Important Extractions: Use --save flag for complex discussions
Set Up Environment Variables: Configure LINEAR_API_KEY and GEMINI_API_KEY for full functionality
Use Aliases: Set up shell aliases for faster access to commands
Leverage Interactive Modes: Use jules-pr list-needing-update and jules-pr list-linear-issues for guided workflows
Backwards Compatibility: Existing jules-pr-manager workflows continue to work with jules-pr manager

📄 License

MIT License - feel free to adapt for your own Jules workflows!

🤝 Contributing

Found a bug or have a feature request? Please open an issue or submit a PR.

Made with ❤️ to make Google Jules development enjoyable.

@ihildy/google-jules-workflow