super-oracle

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 12 Open GitHub ↗

A second-opinion oracle for coding agents, powered by Sakana Fugu Ultra via codex-fugu. Cross-agent skill packaged as a Codex/Claude plugin.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Super Oracle

Super Oracle asks Claude, Codex, and OpenCode to review the same work. They work
separately at first. Each successful reviewer then checks its findings against
the other reports. One model combines the useful findings into a final review.

The default production models are:

- Claude Fable runs at `xhigh`. It can fall back to the rolling `opus` alias when
  Fable reaches its quota cutoff.
- Codex `gpt-5.6-sol` runs at `xhigh`, with fast mode and the fast service tier.
- OpenCode runs Kimi K3 at `max`.
- The latest Claude Opus writes the final synthesis.

The skill works with any agent that can run a shell. The repository includes
plugins for Codex and Claude Code.

## What happens in a run

```mermaid
flowchart TD
    A[Driving agent prepares one briefing] --> B{Enabled providers}
    B --> C[Claude reviews independently]
    B --> D[Codex reviews independently]
    B --> E[OpenCode reviews independently]
    C --> F[Usable initial reports]
    D --> F
    E --> F
    F --> G{Usable report count}
    G -- 2 or more --> H[Healthy providers refine in parallel<br/>using every initial report]
    G -- 1 --> I[Skip refinement<br/>mark the council degraded]
    G -- 0 --> J[Stop and keep partial artifacts]
    H --> K[Chosen provider synthesizes the reports]
    I --> K
    K --> L[Driving agent checks each finding]
    L --> M{Accepted findings remain?}
    M -- Yes --> N[Fix and verify]
    N --> A
    M -- No --> O{Council non-degraded?}
    O -- Yes --> P[Converged]
    O -- No --> Q[Useful result<br/>no convergence claim]
```

1. The enabled reviewers read the same briefing and review the work in parallel.
   A reviewer may use subagents for separate, relevant investigations when its
   runtime supports them. The reviewer chooses those investigations from the
   actual change. The skill does not force a checklist or force delegation.
2. When at least two reports are usable, each healthy reviewer performs one
   refinement pass. It reads all initial reports, checks the repository again,
   and keeps only findings it can support.
3. One provider combines the best available reports. The wrapper writes this
   synthesis to `-o`. It keeps the source reports and checkpoints under
   `OUTPUT.artifacts/reviews/`.

This refinement step comes from
[Research Council](https://github.com/hamelsmu/research-council/tree/ff297a1aef9dbeeae5400699b1f7bc10458fb4c1).
Super Oracle uses one bounded refinement pass. It does not use the research
report format or an open-ended internal loop.

The driving agent makes the final decisions. It must check each finding against
the repository and decide whether to accept it. It fixes only supported findings
that it agrees should be addressed. After it verifies the fixes, it runs a new
complete council. It stops when a non-degraded run has no accepted findings left.

## Install the provider CLIs

Install and sign in to each provider you want to use:

- Install [Claude Code](https://code.claude.com/docs/en/setup) and use a
  first-party Claude subscription session.
- Install [Codex CLI](https://github.com/openai/codex) with access to
  `gpt-5.6-sol` and fast mode.
- Install [OpenCode](https://opencode.ai/docs/cli/) and configure Fireworks AI.

The commands `claude`, `codex`, and `opencode` must be on `PATH`. Super Oracle
skips a missing CLI and prints a warning. The run fails if no reviewer is
available. It also fails if the chosen synthesizer is unavailable, a safety or
dependency check fails, no usable report remains, or synthesis fails.

Every run needs `jq` and `pgrep`. Production Claude runs also need `curl`.
Claude must use first-party subscription authentication.
Super Oracle clears Anthropic API credentials and gateway settings so Claude
cannot switch to API credits without notice.

You can check the CLIs with:

```bash
claude --version
claude auth status
codex --version
opencode --version
```

All child processes run unattended and bypass permission checks. Run Super
Oracle only in a trusted working directory.

## Install Super Oracle

### Codex CLI

```bash
codex plugin marketplace add parlance-labs/super-oracle
codex plugin add super-oracle@parlance-labs
```

### Claude Code

```bash
claude plugin marketplace add parlance-labs/super-oracle
claude plugin install super-oracle@parlance-labs
```

Run `/reload-plugins` or restart Claude Code after installation.

### Amp or another skill-compatible agent

```bash
git clone https://github.com/parlance-labs/super-oracle
# Add plugins/super-oracle/skills to the agent's skill path.
```

## Run it

Ask your agent to use Super Oracle, or run the wrapper yourself:

```bash
plugins/super-oracle/skills/super-oracle/scripts/super-oracle.sh \
  -o oracle-out.md briefing.md
```

You can change the OpenCode model without changing the provider name or output
file names:

```bash
plugins/super-oracle/skills/super-oracle/scripts/super-oracle.sh \
  -O fireworks-ai/accounts/fireworks/models/another-review-model -V max \
  -o oracle-out.md briefing.md
```

Start with the
[briefing template](plugins/super-oracle/skills/super-oracle/reference/briefing-template.md).
The wrapper also gives each reviewer the local
[engineering principles](plugins/super-oracle/skills/super-oracle/reference/code-review-principles.md).
These principles are guidance. They do not limit what a reviewer can inspect,
and the wrapper does not fetch instructions at runtime.

## Options

| Flag or environment variable | What it does |
|---|---|
| `-o FILE` | Writes the final synthesis to this required file. |
| `-C DIR` | Sets the working directory for the review. |
| `-s claude\|codex\|opencode` | Skips one provider. Repeat the flag to skip more than one. `kimi` is an alias for `opencode`. |
| `-y opus\|codex\|opencode` | Chooses the synthesizer. The default is `opus`. `kimi` is an alias for `opencode`. |
| `-m fable\|opus` | Chooses the starting Claude reviewer. The default is `fable`. |
| `-q PERCENT` | Sets the Claude quota cutoff from 1 to 100. The default is `93`. |
| `-O MODEL` | Sets the OpenCode model. The default is `fireworks-ai/accounts/fireworks/routers/kimi-k3-fast`. |
| `-V VARIANT` | Sets the OpenCode variant. The default is `max`. |
| `-n` | Disables configured MCP servers for Claude and Codex. It does not change OpenCode configuration. |
| `-t` | Uses cheap real models for a non-authoritative integration test. |
| `-p SECONDS` | Sets the progress interval on stderr. Use `0` to turn it off. |
| `SUPER_ORACLE_ARTIFACTS_DIR=DIR` | Sets the dedicated directory owned by this run. |
| `SUPER_ORACLE_DEBUG_FILE=FILE` | Keeps Claude dispatch diagnostics in this file. |
| `SUPER_ORACLE_PROGRESS_INTERVAL=SECONDS` | Sets the default heartbeat interval. `-p` takes priority. |
| `SUPER_ORACLE_QUOTA_POLL_INTERVAL=SECONDS` | Sets the in-flight Claude usage check interval from 1 to 300 seconds. The default is `300`. |
| `SUPER_ORACLE_QUOTA_FETCH_TIMEOUT=SECONDS` | Sets the Claude usage lookup timeout from 1 to 30 seconds. The default is `30`. |

If the default Opus synthesizer is unavailable, the wrapper warns and uses a
healthy Codex or OpenCode provider. If you choose a provider with `-y`, the run
fails when that provider is unavailable. It does not silently choose another
provider.

## Files kept after a run

A normal three-provider run creates:

```text
oracle-out.md
oracle-out.md.artifacts/reviews/
├── claude.md
├── claude.partial.md
├── claude.fable.partial.md
├── claude.refined.md
├── claude.refined.partial.md
├── claude.refined.fable.partial.md
├── codex-gpt-5.6-sol.md
├── codex-gpt-5.6-sol.partial.md
├── codex-gpt-5.6-sol.refined.md
├── codex-gpt-5.6-sol.refined.partial.md
├── opencode.md
├── opencode.partial.md
├── opencode.refined.md
├── opencode.refined.partial.md
├── synthesis.md
├── synthesis.partial.md
└── synthesis.fable.partial.md
```

The three `*.fable.partial.md` files contain checkpoints only when a Fable run
was interrupted. The wrapper does not create files for skipped providers. It
prints every active path before it calls a model.

If a refinement fails, the wrapper does not copy the initial report into the
refined file. Synthesis uses the labeled initial report instead. Start each
cycle with a new `-o` file and a new artifact directory if you set one yourself.

OpenCode stops when it reports a quota, token, rate-limit, authentication,
billing, context, or maximum-token error. The wrapper stops and reaps the
OpenCode process. It keeps the partial text, JSON stream, stderr, and checkpoint.
It does not call OpenCode again in that council. Other providers continue when
they still have usable reports.

Any reviewer failure reduces coverage but does not discard usable reports. A
result marked `DEGRADED` may still help, but it cannot prove convergence. A
synthesis failure ends the run with an error and leaves the source files in
place.

## Claude quota checks

Before each production Claude stage, Super Oracle reads the current subscription
usage. By default, it checks again every five minutes while Claude runs. It also
checks the event stream every second for paid extra usage.

Super Oracle starts Fable only when the Fable pool is below the selected cutoff.
While Fable is still running, the wrapper stops it and restarts that stage on the
latest Opus when the Fable pool reaches the cutoff or scoped usage data becomes
unavailable. It keeps a Fable result that finished before the quota guard acted.

The wrapper stops the Claude stage for a shared-session cutoff, an all-model
cutoff, or an Opus cutoff. It also stops for a usage lookup failure or a paid
overage event. The default cutoff is 93 percent, and `-q` changes it. The rolling
`opus` alias avoids a numbered Opus model that would need manual updates.

Reviewers may use subagents for separate, relevant investigations. The prompt
blocks fixed checklist fan-out and recursive Super Oracle calls. Claude `Agent`
and `Workflow` stay enabled. Claude child skills, slash commands, and session
persistence stay disabled.

## Test the integration

```bash
scripts/auth-test.sh       # deterministic fake CLIs, no model usage
scripts/smoke-test.sh      # one real cheap-model council
```

Test mode uses Claude Haiku and Codex `gpt-5.4-mini` at low effort. OpenCode uses
`fireworks-ai/accounts/fireworks/models/deepseek-v4-flash-0731` at `max`. Test
mode runs all three phases and writes the same durable files. Its output names
the cheap synthesizer and says that the result is not an oracle verdict. It
cannot prove convergence.

Test mode has fixed models, so `-m`, `-O`, and `-V` are invalid with `-t`. Set
`SUPER_ORACLE_SMOKE_PRODUCTION=1` only when you mean to test production model
dispatch.

## License

MIT. See [LICENSE](LICENSE).

super-oracle

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README