oracle

• 코드베이스에 대해 대형 AI 모델(GPT‑5.2 Pro, Gemini, Claude 등)에게 심층적인 질문을 하고 싶은데, 단순한 코드 조각이 아닌 관련 소스 파일 전체를 모델이 볼 수 있어야 하는 경우.
• "장시간 사고" 실행이 필요한 경우 — 10분에서 1시간이 걸리는 작업 — CLI가 타임아웃되더라도 다시 연결할 수 있는 저장된 세션을 원하는 경우.
• 토큰 비용을 예측 가능하게 유지하기 위해 glob 패턴, 제외 규칙, .gitignore 인식을 통해 번들에 포함할 파일을 정확히 제어해야 하는 경우.
• 모델에 실제로 전송하기 전에 --dry-run으로 전체 페이로드와 토큰 비용을 미리 확인하고 싶은 경우.

• 여러 번의 주고받는 대화에 걸쳐 실시간 멀티턴 대화 컨텍스트가 필요한 경우 — oracle 실행은 일회성이며, 저장된 세션을 다시 첨부하지 않으면 이전 실행 내용이 기억되지 않습니다.
• 브라우저 엔진을 통해 GPT 또는 Gemini 외의 모델을 사용하려는 경우 — 해당 모델들(Claude, Grok, Codex 등)은 --engine api가 필요합니다.
• 컨텍스트 파일이 각각 1MB를 초과하는 경우 — oracle은 해당 용량 제한을 초과하는 파일을 거부합니다.

oracle은 프롬프트와 파일, 디렉토리, 글로브 패턴을 원하는 만큼 하나의 요청 페이로드로 병합합니다. --file 옵션을 여러 번 전달하거나, 포함 항목과 ! 접두사를 붙인 제외 항목을 혼합하면, oracle이 node_modules, dist, .git 및 기타 불필요한 디렉토리를 자동으로 건너뜁니다.

--engine browser 모드는 브라우저 세션에서 ChatGPT 또는 Gemini를 직접 구동합니다 — 웹 UI를 통해서만 접근할 수 있는 모델에 이상적입니다. 콘텐츠 크기에 따라 인라인으로 붙여넣기할지 또는 첨부 파일로 업로드할지를 자동으로 결정합니다 (인라인의 경우 최대 약 60,000자, 이후에는 파일 업로드).

모든 실행은 ~/.oracle/sessions 아래에 저장됩니다. 긴 브라우저 실행이 연결 해제되거나 시간 초과되는 경우, oracle status --hours 72를 사용하여 최근 세션 목록을 확인하고 oracle session <id> --render를 사용하여 재연결하세요 — 다시 실행하거나 토큰을 소비할 필요가 없습니다.

--dry-run summary 또는 --dry-run full을 --files-report와 함께 실행하면, 실제 요청이 이루어지기 전에 전송될 내용을 정확히 확인하고 토큰 비용을 추정할 수 있습니다. 이를 통해 대규모 코드베이스에서 예상치 못한 초과 사용을 방지할 수 있습니다.

OPENAI_API_KEY가 설정되어 있거나 --engine api가 명시적으로 지정된 경우, oracle은 브라우저 대신 API를 통해 라우팅합니다. 이를 통해 브라우저 엔진에서는 지원되지 않는 Claude, Grok, Codex 및 멀티 모델 워크플로우를 사용할 수 있습니다.

원격 머신에서 oracle serve --host 0.0.0.0 --port 9473 --token <secret>을 사용하여 브라우저 자동화 호스트를 실행한 후, 임의의 oracle 클라이언트를 연결할 수 있습니다. 장시간 실행되는 브라우저 세션을 서버에 오프로드할 때 유용합니다.

개발자는 관련 src/** 파일을 버그 설명, 오류 텍스트, 제약 조건이 포함된 상세한 프롬프트와 함께 묶은 후, oracle --engine browser --model gpt-5.2-pro를 실행합니다. 모델은 전체 컨텍스트를 받아 패치 계획을 반환합니다. 20분 후 세션이 분리되는 경우, 개발자는 다시 실행하는 대신 세션에 재연결합니다.

비용이 많이 드는 실행을 시작하기 전에, 개발자는 oracle --dry-run summary --files-report -p "<task>" --file "src/**"를 실행하여 어떤 파일이 포함될지, 그리고 몇 개의 토큰을 소비할지 확인한 다음, 실제 실행 전에 파일 세트를 줄입니다.

브라우저 엔진이 적합하지 않을 경우, 개발자는 oracle --render --copy -p "<task>" --file "src/**"를 사용하여 번들된 전체 프롬프트를 클립보드에 렌더링한 후, 임의의 채팅 인터페이스에 수동으로 붙여넣습니다.

복잡한 다일(多日) 디버깅 작업을 위해 개발자는 6~30개 문장 분량의 프로젝트 개요, 재현 단계, 정확한 오류 내용을 담은 독립형 프롬프트 파일을 작성하고, 관련된 모든 설정 파일과 진입점 파일을 첨부합니다. 이 프롬프트는 완전히 자급자족적으로 구성되어 있어, 동일한 oracle 명령을 며칠 후에 다시 실행하더라도 동일한 컨텍스트를 유지할 수 있습니다.