Claude for Oracle work: picking a Claude 5 model and designing agents

Claude is now a family of models with very different prices, and the agent tools around it (Claude Code, subagents, skills, MCP) decide most of the result on an Oracle project. This guide is the starting point: which model fits which Oracle job, what it costs, and how to design an agent setup around PL/SQL, APEX and SQLcl. It links to the detailed guides rather than repeating them.

• Editing an APEX app as files with an agent: Vibe-code Oracle APEX with Claude Code + APEXlang.
• Running several agents as a team with a reviewer and budget pacing: How I build Oracle apps with a team of AI agents.
• The same ideas in GitHub Copilot: GitHub Copilot Enterprise for Oracle developers.

The Claude 5 models at a glance

Think in capability tiers rather than names, because the names change with every release. Prices are per million tokens (MTok), input / output, from Anthropic's pricing page at the time of writing (19 October 2026). All four models have a 1M-token context window.

Which model for which Oracle job

Start from the job, not the model. If you're unsure, Anthropic suggests starting with Claude Opus 5.5 for most workloads. On Oracle projects the split below saves money without losing quality, because much of the day is small, repeated edits where the balanced model is half the price and faster:

• Refactoring a large PL/SQL package, or analysing a big Forms module before moving it to APEX → the large model (Claude Opus 5.5) at high effort. These jobs need the whole package or module in view and many careful decisions.
• The hardest long-running work (a multi-day modernization plan, untangling hundreds of interdependent packages) → the most capable model (Claude Fable 5.1). It costs 2.5 times Opus per token, so use it where the extra reasoning pays.
• Everyday APEX pages, APEXlang edits, small PL/SQL changes and code review → the balanced model (Claude Sonnet 5.5). Fast enough to stay in flow, strong enough for most diffs.
• Bulk, repetitive jobs (documenting hundreds of Forms triggers, classifying thousands of error-log lines, tagging tables) → the fast, cheap model (Claude Haiku 5.5), ideally through the Message Batches API.
• Subagents that search, list or summarize inside a larger agent run → the fast model too. The lead agent keeps the bigger model.

Keeping the bill under control

Three levers matter on Oracle projects, where prompts tend to be large (schema dumps, package bodies, Forms XML):

• Prompt caching for repeated context. If every request starts with the same schema dump or coding standard, cache it. Reading from the cache costs a fraction of the input price (0.05× on Opus 5.5 and Sonnet 5.5 at the time of writing); writing it costs 1.25× for the default 5-minute lifetime. Example: a 200,000-token schema on Opus 5.5 costs about $0.80 per request uncached, about $1.00 the first time it is cached and about $0.04 on each cache hit. Caching is a prefix match, so keep the dump byte-identical and put the changing question after it.
• Message Batches for jobs nobody waits for. Batches run asynchronously at 50% of the standard price, and the discount stacks with caching. Each batch request is single-shot (no tool loop), so extract the trigger text or log lines first, then send one request per item.
• Watch the Haiku price step. Claude Haiku 5.5 costs five times more per token when a prompt goes over 100,000 tokens, so keep bulk prompts small: one trigger or one log batch per request.

Calling Claude from Python

For scripts and pipelines (a nightly review of changed packages, a batch job over trigger exports), call the Claude API with Anthropic's official Python SDK (pip install anthropic). This example reviews one package body with the large model, adaptive thinking and high effort. The response is a list of content blocks, so print only the text blocks, and check the stop reason first:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

with open("db/packages/order_api.pkb", encoding="utf-8") as f:
    package_body = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low | medium | high | xhigh | max
    system="You are a senior Oracle PL/SQL reviewer. Report findings only; do not rewrite the package.",
    messages=[{
        "role": "user",
        "content": "Review this package body for: SQL built by string concatenation "
                   "instead of bind variables, WHEN OTHERS THEN NULL, COMMIT or ROLLBACK "
                   "inside reusable procedures, and row-by-row loops that could be one "
                   "SQL statement. For each finding give the line, the rule and a fix.\n\n"
                   + package_body,
    }],
)

if response.stop_reason == "refusal":
    print("The model declined this request.")
elif response.stop_reason == "max_tokens":
    print("The review was cut off at max_tokens. Raise max_tokens and run it again.")
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

On Claude Opus 5.5 thinking is always on, so thinking={"type": "adaptive"} only makes the default explicit; effort is the setting you tune. Change model to claude-sonnet-5-5 or claude-haiku-5-5 to compare cost and quality on your own packages. If the stop reason is refusal, the request was declined and there is no answer text to read. If it is max_tokens, the answer was cut off: thinking counts toward max_tokens, so a long package at high effort can use up the limit before the review is finished. Raise max_tokens and run it again.

Four ways to build an Oracle agent

Anthropic offers four levels, from most control to least work:

1. The Claude API with your own loop. You send messages, run the tools Claude asks for (for example a function that runs a query), and send the results back. Full control, most code.
2. Tool Runner in the Anthropic SDK (beta). You define the tools; the SDK runs the loop for you.
3. Managed Agents (beta). Anthropic hosts the agent loop, and can host the sandbox too. Your database doesn't have to be exposed: a self-hosted sandbox runs the tools on a worker inside your network that needs only outbound HTTPS, and MCP tunnels let Anthropic reach a private MCP server. Tool inputs and results still pass through Anthropic so the model can read them, so keep it to test data.
4. Claude Agent SDK. Claude Code as a library: the same tools, permissions and MCP support, running on your own machine or server.

For day-to-day development, Claude Code itself is usually enough. The rest of this guide sets it up for an Oracle repository.

Set up Claude Code for an Oracle repository

1. Write the rules into CLAUDE.md

Claude Code loads CLAUDE.md (at the repository root or in .claude/CLAUDE.md) at the start of every session. Run /init to get a first draft, then add the Oracle rules Claude can't discover from the code. Anthropic recommends keeping each file under 200 lines; short, checkable rules work best:

# Oracle project rules

## Stack
- Oracle AI Database 26ai. Local development uses the Free container, service FREEPDB1.
- PL/SQL packages live in db/packages as .pks (spec) and .pkb (body) files.
- The APEX app lives in apex/my-app as APEXlang .apx files.
- SQLcl is the only deploy tool.

## PL/SQL
- Bind variables only. Never concatenate values into a SQL string.
- No COMMIT or ROLLBACK inside reusable package procedures; the caller owns the transaction.
- Never write WHEN OTHERS THEN NULL. Log the error and re-raise.
- Keep public signatures in .pks files unchanged unless I ask.

## APEXlang
- Never rename existing components or change their Static IDs.
- After editing .apx files, tell me to run apex validate -input apex/my-app in SQLcl.

## Database access
- Use only the saved SQLcl connection ora26ai_dev (a development schema).
- Show me every DDL or DML statement and wait for my approval before running it.

CLAUDE.md is guidance, not enforcement. Anything that must never happen belongs in permission rules (step 5).

2. Add a read-only PL/SQL reviewer subagent

A subagent is a separate Claude with its own instructions, tools and model. Save the file below as .claude/agents/plsql-reviewer.md. The tools line gives it read-only tools, so it can report problems but never change a file, and model: opus runs it on the large model while your main session can stay on Sonnet:

---
name: plsql-reviewer
description: Reviews PL/SQL changes for bind variables, exception handling and transaction control. Use after files in db/packages change. Read-only.
tools: Read, Glob, Grep
model: opus
---
You review Oracle PL/SQL. You cannot edit files.
For each finding give the file, the line, the rule from CLAUDE.md it breaks
and a corrected snippet. If you find nothing, say so in one line.

Ask Claude to "use the plsql-reviewer subagent on the changes in db/packages", or let it delegate on its own when the description matches. The reviewer only sees its result, not the author's reasoning, which is the point; the agent-team guide shows when to call it.

3. Load Oracle skills

Skills are folders with a SKILL.md file that Claude loads only when a task needs them, so they don't fill the context. Harby's free oracle-ai-skills repository (MIT) has three: oracle-apex, plsql and forms-to-apex. Install them for your user:

git clone https://github.com/Mohamedhrby/oracle-ai-skills
mkdir -p ~/.claude/skills
cp -r oracle-ai-skills/skills/* ~/.claude/skills/

To share them with your team instead, copy the folders into the repository's .claude/skills/. Claude uses a skill when your request matches its description, or you can call one directly with /plsql. Oracle's own APEXlang skill is covered in the APEXlang guide.

4. Connect to the database with the SQLcl MCP Server

SQLcl includes an MCP server that Claude Code starts with sql -mcp. It can only use connections saved in SQLcl with their password. Save one for a development schema in your local FREEPDB1 (never SYS or SYSTEM), then register the server with claude mcp add. Everything after -- is the command Claude Code runs:

sql /nolog
SQL> conn -save ora26ai_dev -savepwd app_dev/<password>@//localhost:1521/FREEPDB1
SQL> exit

claude mcp add --transport stdio sqlcl -- /path/to/sqlcl/bin/sql -mcp

Replace /path/to/sqlcl with your SQLcl folder. The default scope is just you in this project; add --scope project to write the entry to a shared .mcp.json instead. Started this way, SQLcl runs at restrict level 4, its strictest: no host commands and no scripts. Leave it there. The Copilot guide lists the SQLcl MCP tools and the audit table SQLcl writes to.

5. Fence what must never happen

Put limits in .claude/settings.json, where they apply no matter what the prompt says. These rules stop Claude's file tools from reading .env and the wallet folder, and refuse the usual form of git push:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./wallets/**)",
      "Bash(git push *)"
    ]
  }
}

Deny rules are not a full security boundary. A Bash rule matches the command text, so a push written another way (for example git -C . push) isn't matched, and a script that opens a file itself isn't covered by a Read rule. For OS-level enforcement, turn on Claude Code's sandboxing, and keep production secrets off the machine altogether.

Don't add the SQLcl tools (mcp__sqlcl__*) to an allow list, and don't answer "Yes, and don't ask again" on their prompts, because that saves an allow rule. In the default permission mode (labelled Manual) Claude Code then asks before each call, and you see the SQL before it runs. Use plan mode when you only want Claude to read and propose.

Where to go next

• Put it to work on an APEX app: Vibe-code Oracle APEX with Claude Code + APEXlang.
• Scale up to several agents with a reviewer, parity tests and a budget line: How I build Oracle apps with a team of AI agents.
• Use Claude inside APEX itself: APEX AI Assistant.

Check your understanding