chatgpt-oracle

name	chatgpt-oracle
description	Send prompts to ChatGPT Pro via Playwriter browser automation. Use for cross-validation, second opinions, or leveraging GPT-5.2 Pro's research-grade intelligence.

ChatGPT Pro Oracle

Send prompts to ChatGPT (including project GPTs) via Playwriter and get responses back. Connects to your existing Chrome session - no need to quit Chrome or manage cookies.

When to use

• Cross-validate complex reasoning with a second model
• Leverage GPT-5.2 Pro's extended thinking for research tasks
• Query a ChatGPT Project that has custom instructions/files

Requirements

• Chrome with Playwriter extension installed and activated on at least one tab
• User must be logged into ChatGPT in Chrome
• Package: npm install -g @erwinkn/chatgpt-oracle

Configuration

Set CHATGPT_ORACLE_URL to use a custom default URL (e.g., a ChatGPT Project).

Option 1: .env file in repo root

# .env
CHATGPT_ORACLE_URL="https://chatgpt.com/g/g-p-.../project"

Option 2: Environment variable

export CHATGPT_ORACLE_URL="https://chatgpt.com/g/g-p-.../project"

If not set, defaults to https://chatgpt.com/.

Usage

CLI Reference

COMMANDS
  chatgpt-oracle <prompt>                 Send prompt and wait for response
  chatgpt-oracle send <prompt>            Send prompt, return session ID (async)
  chatgpt-oracle poll <session-id>        Check if response is ready
  chatgpt-oracle continue <id> <prompt>   Send follow-up in existing conversation
  chatgpt-oracle sessions                 List active sessions
  chatgpt-oracle close <session-id>       Close an active session

OPTIONS
  -m, --model <model>       Model: auto, instant, thinking, pro (default: pro)
  -u, --url <url>           ChatGPT URL (or set CHATGPT_ORACLE_URL env var)
  -f, --file <path>         Attach file contents (can be repeated)
  -t, --timeout <ms>        Max wait time in ms (default: 900000 = 15min)
  -w, --wait                Wait for completion (poll command)
  --no-wait                 Return immediately (continue command)
  -h, --help                Show full help

CLI Examples

# Simple question
chatgpt-oracle "What is 2+2?"

# Use a specific model
chatgpt-oracle -m instant "Quick question"

# Attach files for code review
chatgpt-oracle -f src/main.ts -f src/utils.ts "Review this code for bugs"

# Use a ChatGPT Project
chatgpt-oracle -u "https://chatgpt.com/g/g-p-.../project" "Analyze this"

# Async mode: send and poll later
chatgpt-oracle send "Complex analysis task"
# Returns: Session ID: abc123...
chatgpt-oracle poll abc123
chatgpt-oracle poll -w abc123  # Wait for completion

# Multi-turn conversation
chatgpt-oracle "Explain SOLID principles"
# Returns: Session ID: xyz789...
chatgpt-oracle continue xyz789 "Give TypeScript examples"

# Long timeout for pro model research
chatgpt-oracle -m pro -t 1800000 "Deep research task"

As a module

import { askChatGPT, sendChatGPT, pollChatGPT, continueChatGPT } from '@erwinkn/chatgpt-oracle';

// Standard usage - wait for response
const result = await askChatGPT({
  prompt: 'Your question here',
  model: 'pro'
});
console.log(result.response);
console.log(result.sessionId); // Use for follow-ups

// Async mode - send and poll later
const { sessionId } = await sendChatGPT({ prompt: 'Complex question' });
// ... do other work ...
const pollResult = await pollChatGPT({ sessionId, wait: true });

// Follow-up in same conversation
const followUp = await continueChatGPT({
  sessionId: result.sessionId,
  prompt: 'Follow-up question'
});

Functions

askChatGPT(options) - Standard usage

Sends a prompt and waits for the complete response.

Parameter	Type	Default	Description
url	string	CHATGPT_ORACLE_URL or https://chatgpt.com/	ChatGPT URL
prompt	string	required	The prompt to send
model	string	'pro'	'auto', 'instant', 'thinking', or 'pro'
files	array	[]	Files to attach: [{path: 'file.py', content: '...'}]
timeout	number	900000	Max wait time in ms (default 15 min)
onProgress	function	null	Callback called every 30s during long waits

Returns:

{ success, response, url, sessionId, elapsed, timedOut, error }

sendChatGPT(options) - Async mode

Sends a prompt and returns immediately with a session ID for polling.

Parameter	Type	Default	Description
url	string	CHATGPT_ORACLE_URL or https://chatgpt.com/	ChatGPT URL
prompt	string	required	The prompt to send
model	string	'pro'	Model to use
files	array	[]	Files to attach

Returns:

{ success, sessionId, url, error }

pollChatGPT(options) - Check/wait for response

Checks if a response is ready or waits for completion.

Parameter	Type	Default	Description
sessionId	string	required	Session ID from sendChatGPT
wait	boolean	false	If true, wait for completion
timeout	number	900000	Max wait time if wait=true

Returns:

{ success, complete, response, url, sessionId, elapsed, timedOut, error }

continueChatGPT(options) - Follow-up messages

Sends a follow-up message in an existing conversation.

Parameter	Type	Default	Description
sessionId	string	required	Session ID from previous conversation
prompt	string	required	The follow-up prompt
files	array	[]	Files to attach
wait	boolean	true	If true, wait for response
timeout	number	900000	Max wait time if wait=true

Returns:

{ success, response, url, sessionId, elapsed, timedOut, error }

Utility functions

• closeSession(sessionId) - Close an active session and clean up resources
• listSessions() - List all active sessions with their elapsed time

Models

• auto: ChatGPT decides how long to think
• instant: Fast responses
• thinking: Extended thinking for complex questions
• pro: Research-grade intelligence (can take 10+ minutes)

Examples

Simple question

import { askChatGPT } from '@erwinkn/chatgpt-oracle';

const result = await askChatGPT({
  prompt: 'What are the key differences between REST and GraphQL?',
  model: 'instant'
});

With a project GPT

import { askChatGPT } from '@erwinkn/chatgpt-oracle';

const result = await askChatGPT({
  url: 'https://chatgpt.com/g/g-p-69590661701c8191958b62e91c543dfb/project',
  prompt: 'Review this architecture decision',
  model: 'pro',
  timeout: 1800000  // 30 min for complex analysis
});

With file attachments

import fs from 'node:fs';
import { askChatGPT } from '@erwinkn/chatgpt-oracle';

const result = await askChatGPT({
  prompt: 'Find bugs in this code',
  files: [
    { path: 'src/main.py', content: fs.readFileSync('src/main.py', 'utf-8') }
  ]
});

Async mode with polling

import { sendChatGPT, pollChatGPT } from '@erwinkn/chatgpt-oracle';

// Start a long-running request without blocking
const { sessionId, url } = await sendChatGPT({
  prompt: 'Analyze this complex codebase architecture',
  model: 'pro'
});
console.log(`Started session: ${sessionId}`);

// Do other work while waiting...

// Check if ready (non-blocking)
let result = await pollChatGPT({ sessionId });
if (!result.complete) {
  console.log(`Still working... ${result.elapsed}s elapsed`);
  // Wait for completion
  result = await pollChatGPT({ sessionId, wait: true });
}
console.log(result.response);

Multi-turn conversation

import { askChatGPT, continueChatGPT } from '@erwinkn/chatgpt-oracle';

// Initial question
const first = await askChatGPT({
  prompt: 'Explain the SOLID principles',
  model: 'pro'
});

// Follow-up using the same session
const second = await continueChatGPT({
  sessionId: first.sessionId,
  prompt: 'Can you give examples in TypeScript?'
});

// Another follow-up
const third = await continueChatGPT({
  sessionId: first.sessionId,
  prompt: 'How does this apply to React components?'
});

Long-running requests

GPT-5.2 Pro can take 10+ minutes for complex tasks. Use sendChatGPT + pollChatGPT for async operation, or run as a background task in Claude Code.

Troubleshooting

• "Extension not running": Click the Playwriter extension icon in Chrome on any tab (icon should turn green)
• "Failed to connect": The CLI auto-retries and kills stale processes. If persistent:
  • Ensure Chrome is running with Playwriter extension active
  • Run lsof -ti:19988 | xargs kill -9 to clear stuck processes
• Model not switching: ChatGPT may have changed their UI; check data-testid values
• Empty response: Increase timeout (-t flag) or check if ChatGPT is rate-limiting