Expert

Expert

Use the expert CLI to ask GPT-5.6 Pro for a second opinion with explicit local context. The CLI uploads named files, starts a background Responses API job, polls until completion, and stores a resumable job record.

Quick Start

Prefer the installed binary when available:

expert ask "Review this implementation for correctness and missing tests." --file src/foo.ts --file test/foo.test.ts

If expert is not on PATH, run it via npx — no install required:

npx -y @bigblueboo/expert ask "Review this implementation for correctness and missing tests." --file src/foo.ts --file test/foo.test.ts

Consultation Workflow

1. Decide whether an external consult is appropriate.

   • Use for hard debugging, architecture choices, security-sensitive code review, tricky API integration, migration plans, or test design.
   • Do not use when the user forbids external API calls, when the task is trivial, or when sensitive secrets would need to be sent.

2. Gather focused context.

   • Attach only files needed to answer the question.
   • Prefer several exact files plus focused globs over one broad repository glob.
   • Repeat --file for multiple files and globs; use directories when the relevant surface is broad.
   • Exclude generated output, vendored dependencies, large artifacts, and secrets.

3. Write a concrete prompt.

   • Include the goal, constraints, known symptoms, what has already been tried, and the desired output shape.
   • Ask for actionable findings, risks, and concrete next steps.
   • For review requests, ask for prioritized bugs and missing tests before summary.

4. Run a dry run for broad context and check the token estimate.

expert ask "Check whether this refactor is safe." --file package.json --file "src/**/*.ts" --file "test/**/*.ts" --dry-run --format json

Check estimated_input_tokens in the output before sending. Trim the attachment list if it approaches the model's capacity (see Context Budget below).

5. Run the consult and wait for the answer.

expert ask "Find correctness risks in this change. Return prioritized findings with file references." \
  --file package.json \
  --file "src/**/*.ts" \
  --file "test/**/*.ts" \
  --exclude "dist/**"

Command Patterns

Use stdin for long prompts or generated context:

git diff -- src test | expert ask "Review this diff for regressions and missing tests." --stdin --file package.json

Use JSON when another tool or script will consume the answer:

expert ask "Summarize API compatibility risks as JSON." --file src/api.ts --format json

Resume after interruption or timeout:

expert resume <job_id>
expert status <job_id>
expert cancel <job_id>

Tune blocking behavior only when needed (--timeout accepts s/m/h, default 360m):

expert ask "Deeply analyze this flaky test." --file test/flaky.test.ts --timeout 12h --poll-interval 5s

Context Budget

GPT-5.6 Pro has a 1,050,000-token context window shared by input, reasoning, and output (128,000 max output tokens). Do not exceed it:

• The CLI estimates input size (~4 characters per token) and refuses to send when the estimate exceeds 900,000 tokens. Prefer trimming the attachment list over raising --max-context-tokens.
• Requests whose input exceeds 272,000 tokens are billed by OpenAI at 2x input / 1.5x output for the entire request. Stay below that unless the extra context clearly earns its cost; the CLI warns when a consult crosses it.
• Byte-based estimates are unreliable for PDFs and other rich formats; leave extra headroom when attaching them.
• When context is too large, split the question into multiple focused consults instead of one oversized one, and summarize earlier answers in follow-up prompts.

Context Selection Guidance

• Include entrypoints, changed files, nearby tests, relevant configs, schemas, docs, and error logs.
• Include package.json, lockfiles, or build configs when dependency or tooling behavior matters.
• Include the failing command and concise output in the prompt or stdin.
• Avoid attaching .env, credentials, private keys, customer data, build directories, node_modules, and unrelated repository snapshots.
• For large repos, start with a dry run and narrow the attachment list before sending.

Interpreting Results

• Treat the consult as expert input, not automatic truth.
• Verify concrete claims against the local repo before editing.
• If the answer is incomplete or asks for more context, rerun expert ask with the missing files and summarize the previous response in the new prompt.
• If the terminal is interrupted, preserve the printed expert resume <job_id> command.
• If the consult exits with code 124, local polling timed out but the job is still running server-side; run the printed expert resume <job_id> command (add --timeout 12h to wait longer). Under --format json, a timeout emits the envelope with timed_out: true.

Defaults

The CLI defaults to gpt-5.6 with reasoning.effort: xhigh, background: true, store: true, a 360 minute (6 hour) timeout, a 5 second polling interval, and a 900,000-token estimated-input cap (--max-context-tokens). reasoning.mode defaults to pro for GPT-5.6 models (GPT-5.6 Pro) and standard for anything else. It requires OPENAI_API_KEY; job records are stored under ~/.expert/jobs unless EXPERT_HOME is set.