Ask first.Write with a way back.Hỏi trước.Ghi luôn có đường lui.

ReplayXem lại

Watch one write.Xem một lần ghi.

What the agent runs to change one package body, start to finish. The person appears once, in the middle — and nothing reaches the database before that.Những lệnh agent chạy để sửa một package body, từ đầu đến cuối. Con người xuất hiện một lần, ở giữa — và không gì chạm tới database trước lúc đó.

$ pythia impact PKG_ORDER
APP_OWNER.PKG_ORDER
  APP_OWNER.PKG_ORDER_API (PACKAGE BODY)
  APP_OWNER.PKG_BILLING (PACKAGE BODY)
    APP_OWNER.PKG_BILLING_JOB (PACKAGE BODY)
-- impact: 3 dependent objects, 3 currently VALID
$ pythia lint db/pkg_order_body.sql
-- 1 file(s): 0 error(s), 0 warning(s), 0 info
$ pythia apply db/pkg_order_body.sql

  PKG_ORDER (PACKAGE BODY) in APP_OWNER — 2 lines changed
  impact: 3 dependent objects, 3 currently VALID

  @@ -13,1 +13,1 @@
  -    UPDATE t_order SET status = 'C'
  +    UPDATE t_order SET status = 'C', confirmed_at = SYSDATE

  Snapshot saved: .pythia/journal/2026-10-15T09-12-04_PKG_ORDER_PACKAGE-BODY

  To apply — the developer approves, then the agent confirms:
    the agent calls the pythia_approve tool (MCP) with token 3f9a2c
# the developer reads the card in the prompt, and approves
  Grant minted — single use, expires in 15 minutes.
$ pythia apply db/pkg_order_body.sql --confirm 3f9a2c

  Applied PKG_ORDER (PACKAGE BODY).
  Compiled clean. No new INVALID objects.
$ echo $?
0

A replay on the sample schema; each output line uses the CLI's own wording, shortened.Phát lại trên schema mẫu; mỗi dòng output dùng đúng câu chữ của CLI, có rút gọn.

Oracle · Data

For the people who own the schema.Cho người giữ schema.

PL/SQL developers change packages that other code leans on. Data engineers ship releases and tune the queries under their pipelines. The agent asks the data dictionary what either of them would check by hand, and changes to data wait behind the strictest gate pythia has.Dev PL/SQL sửa package mà code khác đang dựa vào. Data engineer đưa release lên và tối ưu các truy vấn nằm dưới pipeline. Agent hỏi data dictionary đúng những gì họ vẫn tự kiểm tra, còn thay đổi dữ liệu thì phải qua cổng chặt nhất của pythia.

$ pythia impact PKG_ORDER
APP_OWNER.PKG_ORDER
  APP_OWNER.PKG_ORDER_API (PACKAGE BODY)
  APP_OWNER.PKG_BILLING (PACKAGE BODY)
    APP_OWNER.PKG_BILLING_JOB (PACKAGE BODY)
-- impact: 3 dependent objects, 3 currently VALID

$ pythia explain "select * from t_order where customer_id = :c"
---------------------------------------------------------------
| Id  | Operation         | Name    | Rows  | Cost (%CPU)|
---------------------------------------------------------------
|   0 | SELECT STATEMENT  |         |    42 |   311   (1)|
|*  1 |  TABLE ACCESS FULL| T_ORDER |    42 |   311   (1)|
---------------------------------------------------------------
-- note: full scan of T_ORDER — fine for small tables or most of the rows;
   otherwise check the predicate is indexable (`pythia stats <TABLE>`)

$ pythia stats T_ORDER
-- table
TABLE_NAME  NUM_ROWS  BLOCKS  LAST_ANALYZED     STALE_STATS  …
T_ORDER     1840233   24310   2026-09-02 22:10  YES          …
-- indexes
INDEX_NAME  COLUMNS   UNIQUENESS  STATUS  …
PK_ORDER    ORDER_ID  UNIQUE      VALID   …
-- unindexed fks
CONSTRAINT_NAME    COLUMNS      PARENT_TABLE
FK_ORDER_CUSTOMER  CUSTOMER_ID  T_CUSTOMER
-- note: statistics are STALE
-- note: unindexed foreign keys lock this table on parent DELETE/UPDATE of the key

$ pythia comments T_ORDER
TABLE_NAME  COLUMN_NAME   DATA_TYPE     COMMENTS
T_ORDER                   TABLE         Customer orders, one row each
T_ORDER     ORDER_ID      NUMBER(12,0)  Order key
T_ORDER     CUSTOMER_ID   NUMBER(12,0)
T_ORDER     STATUS        VARCHAR2(1)   N new, C confirmed, X cancelled
T_ORDER     CONFIRMED_AT  DATE
-- 2 of 5 without a comment; pythia comments T_ORDER --scaffold writes the statements to fill in
$ pythia comments T_ORDER --scaffold
COMMENT ON COLUMN T_ORDER.CUSTOMER_ID IS '';
COMMENT ON COLUMN T_ORDER.CONFIRMED_AT IS '';

Sample schema; outputs use the CLI's own wording, columns shortened.Schema mẫu; output dùng đúng câu chữ của CLI, có lược bớt cột.

How it worksCách làm việc

Learn → Ask → DoHọc → Hỏi → Làm

Every task moves through three movements, in this order. The 13 standing rules in AGENTS.md are those movements in enforceable form; pythia guide prints the whole contract.Mỗi việc đi qua ba bước theo thứ tự này. 13 luật trong AGENTS.md là dạng kiểm tra được của ba bước đó; pythia guide in hợp đồng đầy đủ.

SafetyAn toàn

One write, six steps.Một lần ghi, sáu bước.

There is one write path, and a restore takes it too. Each step is a place where a mistake stops instead of landing.Chỉ có một con đường ghi, và restore cũng đi đường đó. Mỗi bước là một chỗ lỗi bị chặn lại thay vì lọt vào database.

1. SnapshotKeep what is there now, so there is a way backLưu bản hiện tại để có đường quay lại
2. ImpactCount what depends on itĐếm object phụ thuộc
3. PreviewDiff, lint, warnings, anything destructiveDiff, lint, cảnh báo, lệnh nguy hiểm
4. ApproveDuyệtOne person, one single-use grantMột người thật, một grant dùng một lần
5. WriteGhiExactly what was previewedĐúng nội dung đã preview
6. VerifyKiểm traCompile errors, objects newly INVALIDLỗi biên dịch, object mới bị INVALID

Anonymous blocks and anything unrecognised are refused. --yes, loosening a policy and turning autopilot on are the developer's own acts: the CLI refuses them without a terminal.Block ẩn danh và câu lệnh không nhận ra được đều bị từ chối. --yes, nới policy và bật autopilot là việc của chính dev: CLI từ chối khi không có terminal của dev.

$ sqlplus app_owner/…@dev @db/01_t_order.sql
PreToolUse:Bash hook error: Writes go through `pythia apply <file>` (one statement)
or `pythia deploy <files>` (a script): snapshot, preview, approval, verify, journal.
sqlplus/SQLcl here would write with none of them (AGENTS.md rule 3). …

Recorded from a real Claude Code session on a sample project, October 2026.Ghi lại từ một phiên Claude Code thật trên dự án mẫu, tháng 10/2026.

Try the guardThử guard

Pick what the agent runs. The verdict is what pythia's PreToolUse hook and the CLI answer, word for word, shortened.Chọn lệnh agent chạy. Kết quả là đúng câu trả lời của hook PreToolUse và CLI của pythia, có rút gọn.

$ pythia impact PKG_ORDER
PreToolUse → allow
pythia read-only command — it cannot write
# no prompt: a read cannot change the database

Three doors to a yes, in orderBa cửa để được duyệt, theo thứ tự

1. pythia_approve (MCP)

   Prompts in every permission mode but dontAsk; no allow rule skips it, and it shows pythia's own card.

   Hỏi ở mọi chế độ quyền trừ dontAsk; không allow rule nào bỏ qua được, và hiện đúng thẻ duyệt của pythia.

2. AskUserQuestion

   The question is exactly pythia approve --card <token>. Pre-filled answers are refused; a missing answer is named.

   Câu hỏi đúng nguyên văn pythia approve --card <token>. Câu trả lời điền sẵn bị từ chối; không có câu trả lời thì hook nói rõ.

3. The developer's terminal

   Terminal của dev

   pythia approve <token>. In dontAsk mode this is the door that remains.

   pythia approve <token>. Ở chế độ dontAsk, chỉ còn cửa này.

Each yes mints a grant: single use, fifteen minutes, bound to the connection and to the content that was previewed. Edit the file and it is a new preview.Mỗi lần duyệt sinh một grant: dùng một lần, hết hạn sau 15 phút, gắn với connection và đúng nội dung đã preview. Sửa file thì phải preview lại.

Autopilot

One approval for a whole session.Duyệt một lần cho cả buổi làm việc.

Twenty identical approvals teach a person to click without reading. A lease replaces them with one honest act: the developer reads a card naming the connection, the statement groups, the hours and a write budget, and approves it once. Every write inside it is still snapshotted, journaled and verified.Hai mươi lần duyệt giống nhau dạy người ta bấm mà không đọc. Lease thay chúng bằng một lần duyệt đúng nghĩa: dev đọc thẻ ghi rõ connection, nhóm câu lệnh, số giờ và số lần ghi tối đa, rồi duyệt một lần. Mọi lần ghi trong lease vẫn có snapshot, nhật ký và kiểm tra.

The lease pauses itself when another object goes INVALID or after five failed writes in a row, and the agent stops to show the developer. pythia autopilot report lists every write with its undo.Lease tự dừng khi có object khác bị INVALID hoặc sau 5 lần ghi lỗi liên tiếp, và agent dừng lại cho dev xem. pythia autopilot report liệt kê mọi lần ghi kèm lệnh undo.

Release scripts, run like SQL*Plus would read themScript release, đọc đúng như SQL*Plus

Skills

An Oracle build pack in 17 skills.Bộ phát triển Oracle trong 17 skill.

Workflows the agent opens at the right moment. using-pythia routes; the rest each own one kind of job, held to the LEAD's conventions.Các quy trình mà agent tự mở đúng lúc. using-pythia điều hướng; mỗi skill còn lại lo một loại việc, theo đúng quy ước của LEAD.

A harness that checks itselfHarness tự kiểm tra chính nó

  ok   claude hooks    PreToolUse guard (reads, approved writes, bypass block): wired
  warn hook launch     .claude/settings.json: `python -m pythia` cannot start pythia here (…) — these hooks
                  show an error on every call they match, while .claude/settings.local.json serves the
                  same hooks with a launcher that starts. Teammates may rely on them — keep them, or remove …
  ok   hook launch     .claude/settings.local.json: `"…/venv/bin/python3" -m pythia` starts pythia
  ok   approval door   pythia_approve MCP tool registered in Claude Code's local scope (overrides .mcp.json)
  ok   claude.md       CLAUDE.md carries the pythia block

An excerpt from 0.15.3 on a sample project upgraded from 0.15.1, paths shortened.Trích từ bản 0.15.3 trên một dự án mẫu nâng cấp từ 0.15.1, đường dẫn được rút gọn.

InstallCài đặt

Two lines.Hai dòng.

Or, with Node.js: npx pythia-plsql does both.Hoặc, nếu có Node.js: npx pythia-plsql làm cả hai.

Filling in connections.jsonĐiền connections.json

{
  "default": "agent_dev",
  "agent_dev": {
    "host": "db-dev", "port": 1521, "service_name": "orclpdb",
    "user": "app_agent[app_owner]", "password": "…",
    "schema": "APP_OWNER"
  },
  "dev": {
    "dsn": "db-dev:1521/orclpdb",
    "user": "app_owner", "password": "…",
    "schema": "APP_OWNER"
  },
  "uat": {
    "dsn": "db-uat:1521/orclpdb",
    "user": "app_agent[app_owner]", "password": "…",
    "schema": "APP_OWNER",
    "protected": true
  }
}

Host and service names are placeholders.db-dev, db-uat và orclpdb là tên giả định.

1. Fill in at least one connection and set "default".
2. Give the agent its own account: pythia agent-user --save, exactly once. It prints three statements for the DBA and saves a <name>_agent entry as the new default; the password is new on every run, so the SQL and the file must come from the same run.
3. Keep it private. install creates it mode 600 and, since 0.15.4, writes it into the project's .gitignore — commit that line, so every clone keeps it out. Never paste the file into a chat or a screenshot.
4. pythia connections lists the entries without secrets; pythia check connects. Using the owner account directly makes check warn — by design.

1. Điền ít nhất một connection và đặt "default".
2. Cho agent tài khoản riêng: pythia agent-user --save, chạy đúng một lần. Lệnh in ba câu SQL cho DBA và lưu entry <tên>_agent làm default mới; mật khẩu sinh lại mỗi lần chạy, nên SQL và file phải từ cùng một lần chạy.
3. Giữ file riêng tư. install tạo file với quyền 600 và, từ 0.15.4, ghi nó vào .gitignore của dự án — hãy commit dòng đó để mọi bản clone đều bỏ qua file. Không dán file vào chat hay ảnh chụp.
4. pythia connections liệt kê các entry mà không in mật khẩu; pythia check thử kết nối. Dùng thẳng tài khoản owner thì check sẽ cảnh báo — đó là chủ ý.

$ pythia install
Created .pythia/connections.json
Added .pythia/connections.json to .gitignore — it holds passwords; commit the .gitignore so every clone keeps it out
$ pythia doctor
  ok   credentials     .pythia/connections.json is git-ignored (.gitignore)
# and where an earlier commit already took it in:
  fail credentials     git tracks .pythia/connections.json — its passwords are in the repository; `git rm --cached
                  .pythia/connections.json`, commit, then change those passwords (the history keeps the old ones)

From 0.15.4 on a sample project, paths shortened.Trích từ bản 0.15.4 trên một dự án mẫu, đường dẫn được rút gọn.

Which connection runs, never a guess: --conn NAME → PYTHIA_CONNECTION → PYTHIA_USER / PYTHIA_PASSWORD / PYTHIA_DSN (skips the file) → the file: one entry is used as is; with several, the folder directly under the project root picks (DEV/… → entry DEV), then "default"; still ambiguous is an error that lists the options.Chọn connection nào, không bao giờ đoán: --conn NAME → PYTHIA_CONNECTION → PYTHIA_USER / PYTHIA_PASSWORD / PYTHIA_DSN (bỏ qua file) → file: một entry thì dùng luôn; nhiều entry thì thư mục ngay dưới gốc dự án quyết định (DEV/… → entry DEV), rồi tới "default"; vẫn mơ hồ thì báo lỗi kèm danh sách.

Upgrading: pip install -U pythia-plsql, then pythia install again in each project — pip runs nothing after an install. A re-run changes nothing that is already right.Nâng cấp: pip install -U pythia-plsql, rồi chạy lại pythia install trong từng dự án, vì pip không tự chạy gì sau khi cài. Chạy lại không đổi gì nếu mọi thứ đã đúng.