oracle
starsforks
How to install oracle?
minghinmatthewlam/agent-guards/oracle
$npx -y skills add minghinmatthewlam/agent-guards --skill oracleUse the @steipete/oracle CLI to bundle a prompt plus the right files and get a second-model review (API or browser) for debugging, refactors, design checks, or cross-validation.
SKILL.md
| 1 | # Oracle (CLI) — best use |
| 2 | |
| 3 | Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat outputs as advisory: verify against the codebase + tests. |
| 4 | |
| 5 | ## Main use case (browser, GPT‑5.2 Pro) |
| 6 | |
| 7 | Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the “human in the loop” path: it can take ~10 minutes to ~1 hour; expect a stored session you can reattach to. |
| 8 | |
| 9 | Recommended defaults: |
| 10 | - Engine: browser (`--engine browser`) |
| 11 | - Model: GPT‑5.2 Pro (either `--model gpt-5.2-pro` or a ChatGPT picker label like `--model "5.2 Pro"`) |
| 12 | - Attachments: directories/globs + excludes; avoid secrets. |
| 13 | |
| 14 | ## Golden path (fast + reliable) |
| 15 | |
| 16 | 1. Pick a tight file set (fewest files that still contain the truth). |
| 17 | 2. Preview what you’re about to send (`--dry-run` + `--files-report` when needed). |
| 18 | 3. Run in browser mode for the usual GPT‑5.2 Pro ChatGPT workflow; use API only when you explicitly want it. |
| 19 | 4. If the run detaches/timeouts: reattach to the stored session (don’t re-run). |
| 20 | |
| 21 | ## Commands (preferred) |
| 22 | |
| 23 | - Show help (once/session): |
| 24 | - `npx -y @steipete/oracle --help` |
| 25 | |
| 26 | - Preview (no tokens): |
| 27 | - `npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"` |
| 28 | - `npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"` |
| 29 | |
| 30 | - Token/cost sanity: |
| 31 | - `npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"` |
| 32 | |
| 33 | - Browser run (main path; long-running is normal): |
| 34 | - `npx -y @steipete/oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"` |
| 35 | |
| 36 | - Manual paste fallback (assemble bundle, copy to clipboard): |
| 37 | - `npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"` |
| 38 | - Note: `--copy` is a hidden alias for `--copy-markdown`. |
| 39 | |
| 40 | ## Attaching files (`--file`) |
| 41 | |
| 42 | `--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated. |
| 43 | |
| 44 | - Defaults (important behavior from the implementation): |
| 45 | - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless you explicitly pass them as literal dirs/files). |
| 46 | - Honors `.gitignore` when expanding globs. |
| 47 | - Does not follow symlinks (glob expansion uses `followSymbolicLinks: false`). |
| 48 | - Dotfiles are filtered unless you explicitly opt in with a pattern that includes a dot-segment (e.g. `--file ".github/**"`). |
| 49 | - Hard cap: files > 1 MB are rejected (split files or narrow the match). |
| 50 | |
| 51 | ## Budget + observability |
| 52 | |
| 53 | - Target: keep total input under ~196k tokens. |
| 54 | - Use `--files-report` (and/or `--dry-run json`) to spot the token hogs before spending. |
| 55 | - If you need hidden/advanced knobs: `npx -y @steipete/oracle --help --verbose`. |
| 56 | - **API runs require explicit user consent** before starting because they incur usage costs. |
| 57 | |
| 58 | ## Sessions + slugs (don’t lose work) |
| 59 | |
| 60 | - Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`). |
| 61 | - Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach. |
| 62 | - List: `oracle status --hours 72` |
| 63 | - Attach: `oracle session <id> --render` |
| 64 | - If ChatGPT finishes but the session still shows **running**, the CLI likely never captured the final response. Reattach to mark completion and write output. |
| 65 | - `oracle session <id-or-slug> --render` |
| 66 | - `~/.oracle/sessions/<slug>/meta.json` should flip to `status: completed`. |
| 67 | - If `models/<model>.log` is empty and `output.log` only shows “Launching browser mode…”, it likely never attached. |
| 68 | - Use `--slug "<3-5 words>"` to keep session IDs readable. |
| 69 | - Duplicate prompt guard exists; use `--force` only when you truly want a fresh run. |
| 70 | |
| 71 | ## Prompt template (high signal) |
| 72 | |
| 73 | Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include: |
| 74 | - Project briefing (stack + build/test commands + platform constraints). |
| 75 | - “Where things live” (key directories, entrypoints, config files, dependency boundaries). |
| 76 | - Exact question + what you tried + the error text (verbatim). |
| 77 | - Constraints (“don’t change X”, “must keep public API”, “perf budget”, etc). |
| 78 | - Desired output (“return patch plan + tests”, “list risky assumptions”, “give 3 options with tradeoffs”). |
| 79 | |
| 80 | ## Safety |
| 81 | |
| 82 | - Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required. |
| 83 | - Prefer “just enough context”: fewer files + better prompt beats whole-repo dumps. |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
