Agents & MCP

# Coding Agents

GitHub Edit page

Oracle is built to be called by coding agents as much as by humans. The flow is always the same: the agent gathers context, hands the bundle to a stronger Pro model, gets a second opinion back.

## #The 30-second wiring

Drop this into the project's `AGENTS.md` or `CLAUDE.md`:

    - Oracle bundles a prompt plus the right files so a Pro model (GPT-5.5 Pro,
      Gemini 3 Pro, Claude Opus) can answer with real repo context. Use when stuck,
      debugging hard bugs, doing architecture review, or cross-validating a plan.
    - Run `npx -y @steipete/oracle --help` once per session before first use.

That's enough for most agents to discover and use Oracle correctly. The patterns below cover the deeper integrations.

## #Claude Code

### #As an MCP server (recommended)

    oracle bridge claude-config --local-browser > .mcp.json

That writes a `.mcp.json` configured for the local browser path, so Claude Code can call `oracle.consult` and `oracle.sessions` without any API keys. Use the MCP `consult` tool with `preset: "chatgpt-pro-heavy"` for ChatGPT GPT-5.5 Pro with Pro Extended thinking. Add `dryRun: true` to inspect the resolved bundle before sending.

See MCP for connection details and other clients.

### #As a skill

Copy the bundled skill into `~/.claude/skills/`:

    mkdir -p ~/.claude/skills
    cp -R skills/oracle ~/.claude/skills/oracle

Then reference `oracle` in `CLAUDE.md`. Claude Code will load `SKILL.md` whenever the trigger conditions match (debugging, refactor, design check).

### #As a slash command

Many users alias Oracle behind a custom `/consult` slash command that wraps `npx -y @steipete/oracle --engine browser …`. Pair with `--browser-tab current` to keep all consults in one ChatGPT conversation.

## #Codex

Copy the same skill into the Codex skills folder:

    mkdir -p ~/.codex/skills
    cp -R skills/oracle ~/.codex/skills/oracle

Then reference it in `AGENTS.md`. Codex will pick it up automatically.

For Codex slash prompts, drop a wrapper in `~/.codex/prompts/oracle.md` that calls Oracle with your preferred defaults (engine, model, follow-up flags).

## #Cursor

Cursor speaks MCP. Drop a `.cursor/mcp.json` like:

    {
      "oracle": {
        "command": "oracle-mcp",
        "args": []
      }
    }

Or use the one-click install. The `oracle` source then shows up in Cursor's MCP picker.

## #Generic CLI usage from any agent

When the agent has shell access, the simplest hand-off is the bundle-on-clipboard fallback:

    oracle --render --copy -p "$TASK" --file "$RELEVANT_FILES"

…then the agent (or a human) pastes into whichever Pro model they have access to. No keys, no MCP, works everywhere.

For autonomous dry-runs, use the JSON preview to inspect the resolved bundle before spending model time:

    oracle --dry-run json --model gpt-5.5-pro -p "$TASK" --file "$RELEVANT_FILES"

Completed runs persist answers, usage, cost, session ids, model choices, and lineage under `~/.oracle/sessions/<id>/`. Exit code is non-zero on failure.

## #Multi-agent shared profile (browser mode)

When multiple agents share one signed-in Chrome profile (the manual-login workflow), Oracle coordinates browser tab slots so parallel runs queue instead of crashing. Tune with:

- `--browser-max-concurrent-tabs` — default 3 simultaneous tabs.
- `--browser-profile-lock-timeout` — wait for the profile lock before sending.
- `--browser-reuse-wait` — wait for a shared Chrome profile before launching.

For the most reliable shared setup: run one signed-in Chrome with remote debugging, point all callers at it via `--remote-chrome <host:port>`. See Browser Mode.

## #Cost / safety hygiene

- Always preview Pro runs. `--dry-run summary --files-report` before a Pro API call on a large bundle. Token counts are a close-enough proxy for dollars.
- Cap file size. `~/.oracle/config.json` → `maxFileSizeBytes`, or `ORACLE_MAX_FILE_SIZE_BYTES`. Default is 1 MB per file.
- Excludes are your friend. `--file "src/**" --file "!**/*.test.ts" --file "!**/*.snap"` cuts most fixtures.
- API mode runs cost real money. If your agent runs Oracle autonomously, scope it: pin `--model`, set `--timeout`, and review the session log. Many users gate API mode behind explicit user consent and let browser mode run free.

## #Patterns that work

- Stuck → Oracle. When the agent has been spinning on the same bug for 3+ turns, hand the failing test plus the involved files to GPT-5.5 Pro. It often spots the issue in one round.
- Plan → Oracle → execute. Draft the plan, ask Claude Opus or Gemini 3 Pro to challenge it, then implement.
- Refactor → cross-check. After a non-trivial refactor, send the diff plus the spec to a different provider than the one that wrote the diff. Catches drift fast.
- Followup chain. Use `--followup <id>` to keep one Pro session alive across iterations rather than re-bundling the whole repo every time. See Followup.