🤖 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.

📋 Table of Contents

- Why These Scripts?
- Quick Installation
- Quick Command Reference
- Optimal Workflow Guide
- Setup Guide
- Key Features
- Advanced Usage
- Priority Classification System
- Supported Integrations
- Auto-Detection Logic
- Performance Features
- Troubleshooting
- Best 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

$3

Install globally for system-wide access:

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

Then use commands directly:

`bash
jules-pr --help
jules-pr-manager
jules-extract-pr
`

$3

Run commands without installing:

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

$3

Install in your project:

`bash
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:

`bash
npx jules-pr --help


or add to your package.json scripts


`

📦 Manual Installation (Development)

For development or customization:

1. Clone the repository

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

2. Install dependencies

`bash
pnpm install
# or npm install / yarn install
`

3. Authenticate GitHub CLI (if not done)

`bash
gh auth login
`

4. Test the setup

`bash
pnpm run pr-manager --help
`

5. Optional: Link globally for development
`bash
npm link
# Now you can use jules-pr anywhere
`

📚 Quick Command Reference

$3

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 - 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

$3

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

$3

Step 1: Find Work

Find issues ready for development

`bash
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.

`bash
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

`bash
jules-pr list-needing-update
`

Step 4: Status Check

`bash
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

$3

Jules Mode is specifically designed for AI coding agents:

`bash
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:

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

$3

`bash


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
`

$3

`bash


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

$3

- 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

$3

1. Install the package globally

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

2. Authenticate GitHub CLI (if not done)

`bash
gh auth login
`

3. Test the installation

`bash
jules-pr --help
`

4. Create configuration file (optional but recommended)

`bash
jules-config-init
`

This creates a jules-workflow.config.js file that you can customize to match your preferences.

5. Recommended: Configure environment variables (see below)

$3

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

`bash


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

$3

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

`json
{
"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

$3

- 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

$3

- 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

$3

- 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

$3

- 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:

`bash
jules-config-init
`

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

$3

`javascript
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!",
},
},
};
`

$3

Customize how comments are classified by priority:

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

$3

Control what sections appear and in what order:

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

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

$3

`javascript
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

$3

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

`bash


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"
`

$3

VSCode Tasks (.vscode/tasks.json):

`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):

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

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

`yaml
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

$3

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

$3

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

$3

- Google Gemini for summaries and analysis
- Extensible for other AI providers

🔍 Auto-Detection Logic

1. Branch Analysis: Extracts Linear IDs (e.g., GRE-123) from branch names like feature/GRE-123-description
2. PR Linking: Finds PRs associated with Linear issue branches
3. Attachment Scanning: Discovers GitHub links in Linear issue attachments
4. 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

$3

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:
`bash
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

$3

`bash


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

1. Install Globally: npm install -g @ihildy/google-jules-workflow for best experience
2. Configure Your Workflow: Run jules-config-init and customize settings to match your preferences
3. Start with Auto-Detection: jules-pr works for most cases
4. Use Jules Mode for AI Sessions: jules-pr --jules for streamlined workflows
5. Daily Workflow Checks: jules-pr summary for status overview
6. Address Reviews Promptly: jules-pr list-needing-update before new work
7. Save Important Extractions: Use --save flag for complex discussions
8. Set Up Environment Variables: Configure LINEAR_API_KEY and GEMINI_API_KEY for full functionality
9. Use Aliases: Set up shell aliases for faster access to commands
10. Leverage Interactive Modes: Use jules-pr list-needing-update and jules-pr list-linear-issues for guided workflows
11. 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.