davidvandijcke/coarse/claude-code

coarse-review (Claude Code)

Runs the full coarse review pipeline on a paper using the local claude -p CLI as the review-reasoning backend. Structure metadata, overview, per-section review, proof verification, and editorial dedup are served by headless Claude Code subprocesses using the user's Claude Max subscription. PDF sources use the user's OpenRouter key locally for ~$0.05-0.15 Mistral OCR and for a small post-extraction vision-QA charge when that check runs; non-PDF sources (.tex, .md, .txt, .docx, .html, .epub) extract locally with no OpenRouter key at all.

This is the same pipeline that powers coarse.ink — only the LLM backend is swapped.

Prerequisites

Check claude --version: Opus 5.5 requires Claude Code 2.1.280 or later, and Sonnet 5.5 requires 2.1.284 or later. Run claude update if needed. Preserve the handoff command's exact --model and --effort, and report any model-access error or fallback shown in the log. Do not change the model or switch to API billing silently.

• uvx preferred, uv acceptable. First run:

command -v uvx || command -v uv

• If neither exists, install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

• Then refresh PATH for the current shell:

export PATH="$HOME/.local/bin:$PATH"

• coarse requires Python 3.12+. If needed, install it with:

uv python install 3.12

• If uv exists but uvx does not, replace uvx --python 3.12 --from ... below with

uv tool run --python 3.12 --from ....

• Refresh the bundled coarse-review skill with an ephemeral install:

uvx --python 3.12 --from 'coarse-ink==1.9.6' coarse install-skills --all --force (If that fails with No such command 'install-skills', you're on a PyPI release that predates the command — upgrade or ignore; the skill bundle is also loadable directly via uvx --from without install.)

• OpenRouter API key required for PDF papers or an explicitly requested deep literature search — PDFs use Mistral OCR (~$0.10 per paper) plus a small vision-QA charge when that check runs. Standard non-PDF reviews extract locally and need no OpenRouter key; --deep-literature-search uses Perplexity Sonar Deep Research for any format and normally adds about $0.30. Skip the probes below only when both conditions are absent. Prefer checking for the key with presence-only probes so you don't needlessly echo its value into the transcript, but if the user hands you the key directly just save it — don't lecture them.

For PDF papers, or whenever deep literature search is requested, check whether OPENROUTER_API_KEY is already configured before running:

• In the environment: test -n "$OPENROUTER_API_KEY" && echo "env: set" || echo "env: missing"
• In a .env file in the current directory: test -f .env && grep -q '^OPENROUTER_API_KEY=' .env && echo ".env: set" || echo ".env: missing"

If the paper is a PDF or deep literature was requested and neither probe reports "set", ask the user:

> I need an OpenRouter API key for PDF OCR (~$0.10) and/or the requested deep literature search (~$0.30). A few options: > > 1. Paste the key here and I'll save it to ~/.coarse/config.toml via uvx --python 3.12 --from 'coarse-ink==1.9.6' coarse setup. Note the key passes through the LLM provider (Anthropic / OpenAI / Google) on its way to me, so treat it as slightly less private than one you typed into a local terminal — rotate at https://openrouter.ai/settings/keys if that worries you. > 2. Set it yourself in a separate terminal: export OPENROUTER_API_KEY=sk-or-v1-... or add it to .env in your current directory, then re-ask me. > 3. Run uvx --python 3.12 --from 'coarse-ink==1.9.6' coarse setup in a separate terminal yourself and paste the key into its interactive prompt — the key never touches this chat. > > Which do you want?

If the user pastes a key here, save it via uvx --python 3.12 --from 'coarse-ink==1.9.6' coarse setup with the pasted value and confirm it's stored. Their chat, their choice.

• claude CLI logged in.

How to run

Get the paper path from the user. PDF is most common but any coarse-supported format works.

If they already have a pre-extracted markdown (from a previous coarse run), pass it with --pre-extracted to skip OCR.

Launch in the background, then wait with `--attach` — two Bash calls, one approval per call. A full review takes 10-25 minutes, which exceeds Claude Code's default 2-minute tool timeout, so you can't just run coarse-review in the foreground. Instead, split the run into two steps: --detach starts a background worker and returns in ~2 seconds; --attach blocks on the worker's PID and streams the log until completion, emitting a heartbeat every 30 seconds of log idleness so the Bash tool sees activity.

Use a per-review unique log file so parallel runs in the same shell don't clobber each other's output:

# Pick a unique suffix — use the paper filename stem or `$(date +%s)`:
LOG=/tmp/coarse-review-$(basename <paper_path> .pdf).log
 
# STEP 2a — launch (returns within 2 seconds with Review PID + Log file)
uvx --python 3.12 --from 'coarse-ink==1.9.6' \
  coarse-review --detach --log-file "$LOG" \
  <paper_path> --host claude [--model claude-opus-5] [--effort high] [--deep-literature-search]
 
# STEP 2b — wait (one blocking call, ~10-25 min, emits heartbeats)
uvx --python 3.12 --from 'coarse-ink==1.9.6' \
  coarse-review --attach "$LOG"

Run the attach command with Bash's run_in_background option, then use the task-output tool to wait for that same task until it exits. Use the documented tool timeout limits; do not assume a 45-minute Bash timeout is accepted. If the tool ends the watcher early, re-run the same attach command to reconnect. Never repeat --detach while that worker is running. Attach exit codes: 0 complete, 1 failure marker, 2 silent crash, 3 missing pidfile, 124 attach's own 30-minute timeout, 130 user interrupt.

When attach exits with code 0, do NOT hunt across the filesystem for the review file. coarse-review prints the authoritative paths in the final log lines:

rg '^  view:|^  local:' "$LOG"

• local: is the exact markdown path that was written, even if uvx used a temporary working directory.
• view: is the canonical coarse web URL in handoff mode.

If view: says unavailable, treat that as a callback failure and report only the local path. Do not try to discover another web URL, and do not run broad find, locate, lsof, or whole-computer searches trying to rediscover the output.

Available models: claude-opus-5-5 (default), claude-sonnet-5-5, claude-fable-5-1, claude-opus-5, claude-sonnet-5, claude-opus-4-8, claude-haiku-4-5. Available effort levels: low, medium, high (default), max.

If the user came from the coarse web form, they'll paste a handoff URL instead of a local file path. The paper is a REMOTE resource at that URL — do NOT search for a local PDF and do NOT ask the user for a file path. Same two-step launch+attach pattern:

LOG=/tmp/coarse-review-$(date +%s).log
 
# STEP 2a — launch
uvx --python 3.12 --from 'coarse-ink==1.9.6' \
  coarse-review --detach --log-file "$LOG" \
  --handoff https://coarse.ink/h/<token> --host claude [--model ...] [--effort ...]
 
# STEP 2b — wait (use the same background-task mechanism as local mode)
uvx --python 3.12 --from 'coarse-ink==1.9.6' \
  coarse-review --attach "$LOG"

This downloads the paper from the handoff URL, runs the pipeline, and POSTs the final review back so it shows up at https://coarse.ink/review/<paper_id>?token=<access_token>. The view: line in the log will already include the signed access token — use that URL as-is.

When the script completes (you'll be notified), read the output markdown and show the user:

• Output path
• Web URL from the view: line in handoff mode
• Recommendation (accept / revise_and_resubmit / reject)
• Top 2-3 macro issues from the overall feedback section
• Total comment count

Notes

• uvx --python 3.12 --from ... coarse-review ... runs coarse from a temporary environment, so the agent does not mutate the user's global tool install.
• The review process runs locally using the user's own Claude Code login; coarse.ink only receives the finished markdown callback.
• The driver monkey-patches coarse.llm.LLMClient → coarse.headless_clients.ClaudeCodeClient, which spawns claude -p subprocesses for every pipeline LLM call.
• Host-CLI env vars (CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, etc.) are stripped from the subprocess environment so nested sessions don't conflict with the parent.
• If a single claude -p call exceeds 30 minutes, it's killed and the pipeline continues without that section's comments.
• Check progress via tail -f $LOG where $LOG is the per-review log path you set in step 2 (e.g. /tmp/coarse-review-<paper-stem>.log). Prefer the coarse-review --attach "$LOG" pattern above — it replaces per-poll tail calls with a single blocking watch command that emits heartbeats every 30 seconds of log idleness.