modjules - the agent-ready SDK for Jules

> Status: Useful tool but still experimental. Supported and moving fast to improve.

Making Jules Agent-Ready

Agents thrive on simple actions, persistent memory, and reactive updates. modjules provides an tool and memory agent toolkit on top of the Jules REST API.

- Tool Oriented: Abstracts multi-step API choreographies into single, awaitable tool calls that an agent can easily execute. (e.g., create session → poll for status → fetch result)
- Persistent State: Provides external memory, retaining conversational context across turns without burdening your agent's context window.
- Reactive Streams: Converts passive REST polling into push-style Async Iterators, allowing your agent to efficiently _observe_ progress in real-time without managing complex polling logic.

Core Usage

``ts
import { jules } from 'modjules';

const session = jules.run({
prompt: Fix visibility issues in the examples/nextjs app.

Visibility issues
- White text on white backgrounds
- Low contrast on button hover

Instructions
- Update the global styles and page components to a dark theme with the shadcn zinc palette.
,
source: { github: 'davideast/modjules', branch: 'main' },
});

for await (const activity of session.stream()) {
switch (activity.type) {
case 'progressUpdated':
console.log([BUSY] ${activity.title});
break;
case 'planGenerated':
console.log([PLAN] ${activity.plan.steps.length} steps.);
break;
case 'sessionCompleted':
console.log('[DONE] Session finished successfully.');
break;
case 'sessionFailed':
console.error([FAIL] ${activity.reason});
break;
}
}

// Get the pull-request URL once complete
const { pullRequest } = await session;
if (pullRequest) {
console.log(PR: ${pullRequest.url});
}
`

Batch Processing

Process multiple items in parallel with jules.all(). This method is designed to feel like Promise.all() but with built-in concurrency control.

`javascript
const todos = ['Fix login bug', 'Update README', 'Refactor tests'];

// Processes items concurrently (default: 3 at a time)
const sessions = await jules.all(todos, (task) => ({
prompt: task,
source: { github: 'user/repo', branch: 'main' },
}));

// The results array preserves the order of the input array
console.log(Created ${sessions.length} sessions.);
`

For more control, you can pass an options object:

`javascript
const sessions = await jules.all(largeList, mapFn, {
concurrency: 10, // Run 10 at a time
stopOnError: false, // Don't stop if one fails
delayMs: 500, // Wait 500ms between starting each item
});
`

$3

The local cache can be queried instantly without network latency using the .select() method.

`typescript
// Query your local cache instantly without network latency.
const errors = await session.select({
type: 'sessionFailed',
limit: 10,
});
`

Installation

`bash
npm i modjules


OR


bun add modjules
`

Cross-Platform Usage

The modjules SDK is designed to work seamlessly in both Node.js and browser environments. It uses conditional exports in its package.json to automatically provide the correct implementation for your platform.

$3

In a Node.js environment, the SDK defaults to using the local filesystem for caching session activities in a .jules/cache directory. This provides a persistent, restart-safe experience.

`typescript
// Imports the Node.js version by default
import { jules } from 'modjules';

const session = await jules.session({
prompt: 'Refactor the user authentication module.',
source: { github: 'your-org/your-repo', branch: 'develop' },
});
`

$3

When used in a browser environment (e.g., in a web application bundled with Vite, Webpack, or Rollup), the SDK automatically uses a browser-specific implementation that leverages IndexedDB for storage. This allows your web application to maintain session state locally.

> TEST ONLY DO NOT USE IN PRODUCTION: The browser module is designed for testing and prototyping only. Never expose your JULES_API_KEY in a production application.

To use the browser version, you can explicitly import it and must configure it with the test-only API key option:

`typescript
// Explicitly import the browser-optimized version
import { jules } from 'modjules/browser';

// Initialize with the test-only option
const testJules = jules.with({
apiKey_TEST_ONLY_DO_NOT_USE_IN_PRODUCTION: '...',
});

const session = await testJules.session({
prompt: 'Refactor the user authentication module.',
source: { github: 'your-org/your-repo', branch: 'develop' },
});
`

$3

There are two primary strategies for handling platform-specific code, and modjules is designed to support both.

1. Automatic Resolution (Recommended for most cases): Modern bundlers that support the exports field in package.json can automatically select the correct file based on the environment. For example, Vite, when building for the browser, will see the browser condition in the exports map and use the dist/browser.es.js file. This is the ideal scenario, as it requires no changes to your import statements.

`typescript
// In a browser environment, the bundler will automatically
// resolve this to the browser-specific build.
import { jules } from 'modjules';
`

2. Explicit Imports: In some cases, you may want to be explicit about which version you are using, or your tooling may not fully support conditional exports. In these situations, you can use a direct import path.

`typescript
// Always imports the browser version, regardless of bundler configuration
import { jules } from 'modjules/browser';
`

When to choose which?

- Use the default import (modjules) whenever possible. It's cleaner and relies on the standard module resolution features of the JavaScript ecosystem.
- Use the explicit import (modjules/browser) if you need to override the bundler's resolution, if you are working in an environment that doesn't support conditional exports, or if you want to be very clear in your code that you are using the browser-specific version.

Authentication / API Key

`bash
export JULES_API_KEY=
`

Interactive Usage

Use jules.session() for interactive workflows to observe, provide feedback, and guide the process. The SessionClient object maintains state across multiple interactions.

`typescript
import { jules } from 'modjules';

const session = await jules.session({
prompt: 'Refactor the user authentication module.',
source: { github: 'your-org/your-repo', branch: 'develop' },
});

console.log(Session created: ${session.id});
console.log('Waiting for the agent to generate a plan...');

// Wait for the specific state where the plan is ready for review
await session.waitFor('awaitingPlanApproval');
console.log('Plan is ready. Approving it now.');
await session.approve();

// Ask a follow-up question
const reply = await session.ask(
'Start with the first step and let me know when it is done.',
);
console.log([AGENT] ${reply.message});

// Wait for the final result of the session
const outcome = await session.result();
console.log(✅ Session finished with state: ${outcome.state});
`

Deep Dive

$3

Sessions progress is observed through the .stream() method that is available on both the AutomatedSession and SessionClient objects. An AutomatedSession is created via jules.run() and a SessionClient is create via jules.session(). The .stream() method returns an AsyncIterator to observe the agent's progress.

`typescript
for await (const activity of session.stream()) {
switch (activity.type) {
case 'planGenerated':
console.log(
'Plan:',
activity.plan.steps.map((s) => s.title),
);
break;
case 'agentMessaged':
console.log('Agent says:', activity.message);
break;
case 'sessionCompleted':
console.log('Session complete!');
break;
}
}
`

$3

Session progress is represented through an Activity object. Activities can contain artifacts, such as code changes (changeSet), shell output (bashOutput), or images (media). The SDK provides rich objects with helper methods for interacting with them.

`typescript
// (Inside a stream loop)
for (const artifact of activity.artifacts) {
if (artifact.type === 'bashOutput') {
// The .toString() helper formats the command, output, and exit code
console.log(artifact.toString());
}
if (artifact.type === 'media' && artifact.format === 'image/png') {
// The .save() helper works in both Node.js and browser environments
await artifact.save(./screenshots/${activity.id}.png);

// Get a URL for display or download (works cross-platform)
const url = artifact.toUrl();
console.log('Screenshot URL:', url);
}
}
`

$3

You can configure timeouts and polling intervals by creating a configured client.

#### Multiple API Keys

`typescript
import { jules } from 'modjules';

// The default jules client initialized with process.env.JULES_API_KEY
const session = jules.session('');

// Initializes a jules client with another API key
const customJules = jules.with({ apiKey: 'other-api-key' });
const session = customJules.session('');
`

#### Polling & Timeouts

`typescript
import { jules } from 'modjules';

const customJules = jules.with({
pollingIntervalMs: 2000, // Poll every 2 seconds
requestTimeoutMs: 60000, // 1 minute request timeout
});

// Use the jules client the same as the default
const session = jules.session('');
`

$3

The SDK throws custom errors that extend a base JulesError. This makes it easy to catch all SDK-related exceptions.

`typescript
import { jules, JulesError } from 'modjules';

try {
const session = await jules.session({ ... });
} catch (error) {
if (error instanceof JulesError) {
console.error(An SDK error occurred: ${error.message});
} else {
console.error(An unexpected error occurred: ${error});
}
}
`

API Overview

This is a high-level overview of the main SDK components.

- Core:
- jules: The pre-initialized client.
- jules.with(options): Creates a new client with custom configuration.
- jules.session(): Creates or rehydrates a session. Returns a SessionClient.
- Session Control:
- session.ask(): Sends a message and awaits the agent's reply.
- session.send(): Sends a fire-and-forget message.
- session.approve(): Approves a pending plan.
- session.waitFor(): Pauses until the session reaches a specific state.
- session.waitForCompletion(): Awaits the final outcome of the session.
- Observation:
- session.stream(): Returns an async iterator of all activities (history + live).
- session.history(): Returns a stream of locally cached activities.
- session.updates(): Returns a stream of live activities from the network.
- session.select(query): Queries the local activity cache.
- session.info(): Fetches the latest session state.
- Artifact Management:
- artifact.save(): Decodes the base64 data and saves it. In Node.js, it writes to the filesystem. In the browser, it saves to IndexedDB.
- artifact.toUrl(): Returns a data: URI for the artifact data, usable in both Node.js and browser.
- artifact.toString(): Returns a formatted string that combines the command, exit code, stdout, and stderr`, to simplify log display.