# Oracle

Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and...

- Repository: https://github.com/SafeAI-Lab-X/ClawKeeper (1020 stars)
- Category: AI and agents
- License: see repository
- Last updated: 2026-08-17
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add SafeAI-Lab-X/ClawKeeper --skill oracle -g -a claude-code -y`
Codex: `npx skills add SafeAI-Lab-X/ClawKeeper --skill oracle -g -a codex -y`
Cursor: `npx skills add SafeAI-Lab-X/ClawKeeper --skill oracle -g -a cursor -y`
Gemini CLI: `npx skills add SafeAI-Lab-X/ClawKeeper --skill oracle -g -a gemini-cli -y`

## Description

Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# oracle, best use

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 output as advisory: verify against code + tests.

## Main use case (browser, GPT‑5.2 Pro)

Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.

Recommended defaults:

- Engine: browser (`--engine browser`)
- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)

## Golden path

1. Pick a tight file set (fewest files that still contain the truth).
2. Preview payload + token spend (`--dry-run` + `--files-report`).
3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).

## Commands (preferred)

- Help:
  - `oracle --help`
  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).

- Preview (no tokens):
  - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
  - `oracle --dry-run full -p "<task>" --file "src/**"`

- Token sanity:
  - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`

- Browser run (main path; long-running is normal):
  - `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`

- Manual paste fallback:
  - `oracle --render --copy -p "<task>" --file "src/**"`
  - Note: `--copy` is a hidden alias for `--copy-markdown`.

## Attaching files (`--file`)

`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.

- Include:
  - `--file "src/**"`
  - `--file src/index.ts`
  - `--file docs --file README.md`

- Exclude:
  - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"`

The rest: https://github.com/SafeAI-Lab-X/ClawKeeper/blob/HEAD/legacy/clawkeeper-watcher/skills/oracle/SKILL.md