Workflows

Sessions

GitHub Edit page

Every Oracle run gets an id, a slug, and a folder. You can list runs, render the prompts you sent, replay the answer, and continue from any of them. This page is the lifecycle reference.

#Where sessions live

~/.oracle/sessions/<id>/
├── meta.json                # status, model(s), cost, lineage
├── prompt.md                # assembled bundle (what was sent)
├── response.md              # the model's answer (when complete)
├── log.jsonl                # per-event log
└── artifacts/               # browser-only: transcript, generated images/files, deep-research-report.md

Override the root with ORACLE_HOME_DIR=/some/path.

#Listing

oracle status                  # last 20 sessions
oracle status --hours 168      # last week

status shows status, model, mode, timestamp, character count, cost, and slug — with a tree of --followup lineage:

Recent Sessions
Status    Model         Mode    Timestamp           Chars    Cost  Slug
completed gpt-5.2-pro   api     03/01 09:00 AM      1800   $2.110  architecture-review-parent
completed gpt-5.2-pro   api     03/01 09:14 AM      2200   $2.980  ├─ architecture-review-followup
running   gpt-5.2-pro   api     03/01 09:22 AM      1400        -  │  └─ implementation-pass
pending   gpt-5.2-pro   api     03/01 09:25 AM       900        -  └─ risk-check

#Replaying

oracle session <id>            # print metadata + answer
oracle session <id> --render   # print the prompt that was sent

Use the slug or a unique id prefix; Oracle resolves both.

#Reattach

GPT-5.x Pro answers can take 10–60 minutes. API runs detach by default — Oracle returns the session id, you reattach later:

oracle status                  # find the running one
oracle session <id>            # blocks until done, then prints the answer

Every new run prints a lifecycle block so foreground and detached behavior is explicit:

Session: 20260515-name-panel
Mode: api background
Models: 3 parallel
Detach: yes, polling
Reattach: oracle session 20260515-name-panel

oracle status uses compact mode labels such as api/fg, api/bg, br/fg, and br/bg; oracle session <id> shows the persisted execution state.

To keep the original CLI attached until completion, pass --wait:

oracle --wait --model gpt-5.5-pro -p "Long architecture review" --file "src/**"

For API runs, --wait executes the request in the foreground. Local Pro browser runs use a detached worker even with --wait, while the original CLI stays attached to the session log. This lets the browser worker capture and save the answer if the foreground CLI exits unexpectedly. Pressing Ctrl-C still cancels the worker and exits with code 130.

MCP callers can make the same ownership split explicit for any local run: call consult with waitForCompletion:false, then call wait with the returned session id. wait.timeoutMs bounds only the caller's wait; timeout, request cancellation, or MCP transport closure does not cancel the detached worker. Omit the timeout to wait until a terminal status, or use 0 for an immediate snapshot.

Reattachment recognizes prompt echoes even when spacing or line breaks differ, and keeps waiting for assistant content instead of treating the echoed prompt as an answer.

For browser runs, ChatGPT sometimes redirects mid-page-load. The auto-reattach flags poll the existing tab without manual intervention:

oracle --engine browser \
  --browser-timeout 6m \
  --browser-auto-reattach-delay 30s \
  --browser-auto-reattach-interval 2m \
  --browser-auto-reattach-timeout 2m \
  -p "Long UI audit" --file "src/**"

See Browser Mode for the full set.

#Restart

oracle restart <id>            # re-run with the same prompt + files

Useful when a transient browser/API error truncated the answer. Restart copies the bundle, opens a new session, and links lineage back.

#Follow up

Continue a saved ChatGPT browser conversation or an OpenAI / Azure Responses API session with new context:

oracle --followup <id> -p "Re-evaluate with these files" \
  --file "src/migrations/**"

Browser followup reopens the exact saved conversation and inherits its browser configuration and model. For multi-model API parents, pick the lineage with --followup-model. See Followup for the full flow and the formats --followup accepts (session ids, slugs, or resp_… response ids).

#Background mode

Force a Responses API run into background mode (create + retrieve) regardless of model defaults:

oracle --background --model gpt-5.5-pro -p "..." --file "src/**"
oracle --no-background --model gpt-5.5 -p "..." --file "src/**"

GPT-5.x Pro defaults to background; non-Pro models block by default. Override per-run when needed.

#Pruning

oracle status --clear --hours 168   # delete sessions older than a week

--clear is destructive — preview without it first. Sessions are local files, so rm -rf ~/.oracle/sessions/<id> works too.

#Stale / zombie detection

oracle status flags stale sessions (process gone, no recent log activity). Tune with:

  • --zombie-timeout <ms|s|m|h> — cutoff for "stale."
  • --zombie-last-activity — use last log entry instead of session start.

#Slugs

Every run gets a default slug derived from the prompt. Override with --slug "my-thing" for stable names you can reference later (oracle session my-thing).

#Browser harvest identity

oracle session <id> --harvest and --live reuse the saved Chrome transport, including the browser WebSocket endpoint and approval wait for attach-running sessions. This supports Chrome configurations without HTTP target discovery. If the saved tab is gone, recovery reopens the saved conversation through the same endpoint. Keep Chrome running with remote debugging enabled and allow its connection prompt when requested; transport failures identify the operation and endpoint instead of displaying an empty error. Transient ChatGPT status notices appended outside the user content do not invalidate the submitted prompt hash; the stable user message ID and exact prompt text must still match.

Browser harvest and live-tail compare the observed conversation with saved runtime, archive, artifact-source, and transcript-header identities. A mismatch is retained under browser.harvest.integrity and shown as a browser warning; an implicit harvest fails with conversation-identity-mismatch before exporting the newly harvested answer. Existing transcripts and answer logs are preserved.

Implicit harvest also waits for an assistant answer paired with the latest user turn, up to the saved browser input timeout. New browser sessions record a fingerprint of each rendered, committed user turn and its stable message ID before waiting for its answer, including repeated follow-ups. A mismatch preserves the original output; an unconfirmed submission requires waiting or explicit tab inspection.

Older sessions without a fingerprint retain their existing recovery behavior, with a warning that only latest user/assistant pairing can be checked. Their submitted file context cannot be reconstructed reliably from saved metadata.

An explicit --browser-tab override still permits inspecting another target, but records the mismatch and does not reassign the original capture. Unavailable recorded transcript headers or unreadable recorded conversation URLs are marked unverified. Matching known conversation IDs does not by itself prove that an answer belongs to the original prompt.

#Naming conventions

Pair --slug with conventional prefixes for browseability:

  • arch-… — architecture / design review
  • bug-… — debugging session
  • refactor-… — refactor cross-check
  • plan-… — planning consult
  • dr-… — Deep Research run

Then oracle status --hours 720 | grep arch- shows your last month of architecture work.