cureview 0.8.2

CURe PR review sandboxes powered by ChunkHound and configurable LLM presets

[!WARNING] Read this first: ChunkHound and disk requirements. CURe cannot run reviews until ChunkHound is fully installed, configured, and confirmed working end-to-end. When possible, use the latest ChunkHound main branch so CURe gets current indexing and research behavior.

CURe creates ChunkHound-backed indexes and ad-hoc DuckDB databases inside review sandboxes. On large repositories, these artifacts can consume vast disk space; CURe is best suited to small and medium projects where the ChunkHound index is measured in a few GB, not hundreds.

Use a fast, spacious SSD, and run cure clean regularly to remove old sandboxes and cached state you no longer need.

CURe

CURe ("Code Under Review") is a CLI for running pull request reviews inside isolated sandboxes, with ChunkHound-backed code search/research and a configurable review agent on top.

It is for human operators who want a repeatable way to run or delegate PR review work without letting the source checkout be mutated. LLM agents can assist by following documented commands, but installation, persistent configuration, secrets, network access, local agent selection, and sandbox permissions remain operator-controlled.

If you are using CURe from an agent session, treat SKILL.md as an assisted checklist: run only the steps your environment and operator allow, and stop when setup or permissions are ambiguous.

Quick Links

• Why CURe
• Install And First Review
• Example Flows
• Agent And Setup Notes
• Core Commands
• Secondary Standalone Install
• Advanced / Pre-Provisioned Environments
• Minimal Config
• Jira CLI
• Tests

Why CURe

Use CURe when you want to:

• review a GitHub PR from a disposable sandbox instead of the working repo
• standardize how operators start, observe, resume, and clean review runs, including agent-assisted runs
• document an assisted path from an operator-approved install or disposable setup to "review in progress" without promising unattended bootstrap

CURe is different from an ad-hoc manual agent review because the project checkout stays untouched, the review state stays on disk, and the workflow is resumable instead of prompt-by-prompt improvisation.

CURe is not for:

• ad-hoc in-place repo review where the agent should work directly in the project checkout
• environments that cannot install tools or authenticate the required external systems

Install And First Review

Persistent install:

uv tool install cureview
cure setup
cure doctor --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new

cure setup reuses an existing chunkhound already on PATH by default. Pass --chunkhound-source release or --chunkhound-source git-main only when the operator has approved CURe installing or replacing that binary explicitly, or --skip-install when chunkhound is already available and should be left untouched.

Disposable assisted run path:

uvx --from cureview cure setup
uvx --from cureview cure doctor --pr-url <PR_URL> --json
uvx --from cureview cure pr <PR_URL> --if-reviewed new

This disposable path assumes package execution, network access, config writes under the selected XDG roots, and any ChunkHound install are permitted by the operator and sandbox. If one of those prerequisites is blocked or ambiguous, stop and ask the operator instead of improvising.

Keep the README focused on the landing page and first success. For the full operator-controlled agent-assistance checklist, including local setup inspection rules and operator handoff wording, use SKILL.md.

Example Flows

Example 1: clean public package install to first review

This is the primary public path and matches the package prove-out used for the first successful public release:

uv tool install cureview
cure setup
cure doctor --pr-url https://github.com/chunkhound/chunkhound/pull/220 --json
cure pr https://github.com/chunkhound/chunkhound/pull/220 --if-reviewed new

The v0.1.2 public release prove-out verified the package-first setup flow in a clean temp-home install. cure setup is the primary public setup command.

Example 2: disposable assisted run from the one-sentence kickoff

Use this assisted run surface when the review happens inside a disposable sandbox or agent session where the operator has approved package execution and temporary config/state/cache writes:

tmp_root="$(mktemp -d)"
export XDG_CONFIG_HOME="$tmp_root/config"
export XDG_STATE_HOME="$tmp_root/state"
export XDG_CACHE_HOME="$tmp_root/cache"

uvx --from cureview cure setup
uvx --from cureview cure doctor --pr-url <PR_URL> --json
uvx --from cureview cure pr <PR_URL> --if-reviewed new

If CURe is already partially configured, inspect the active local setup before creating a fresh one:

- the active `cure.toml`
- the JSON file resolved from `[chunkhound].base_config_path`
- repo-root `chunkhound.json` and `.chunkhound.json` as ask-first ChunkHound setup hints

On a TTY, cure setup acts as an operator-facing setup wizard. The wizard can keep the current configured base config, adopt a repo-root chunkhound.json / .chunkhound.json, accept an absolute custom base-config path, or generate the default CURe-managed base config. It also detects the installed codex executable, can persist an approved local CLI-agent choice through default_preset, and can install ChunkHound before returning to the original command when chunkhound is still missing on PATH and the operator has approved that install.

Example 3: what a finished review produces

A normal review run leaves behind resumable session state plus a review artifact with stable headings:

<session_dir>/
  meta.json
  review.md

**Summary**: ...
## Business / Product Assessment
### In Scope Issues
## Technical Assessment
### In Scope Issues

Review output uses two independent lenses:

• Business / Product Assessment uses product/ticket scope.
• Technical Assessment uses implementation scope.

Agent And Setup Notes

Ensure git, curl, and ca-certificates are present before bootstrap. Install uv only in an environment where package installation is operator-approved; otherwise stop with the missing prerequisite and the exact command the operator can run.

Use cure doctor --pr-url <PR_URL> --json as the source of truth for inspect-first setup. Its repo_local_chunkhound payload plus the repo-local-chunkhound check and executor-network advisory check surface the same setup hints in machine-readable and text forms.

If repo-local ChunkHound config exists, summarize what it contains and ask the operator whether it should be reused. Do not silently adopt it in this public contract.

Commands that actually require bootstrap now fail or repair approved non-secret defaults earlier instead of surfacing late config or agent-selection errors. On a TTY, cure pr, cure resume, cure followup, cure cache prime, and cure interactive can enter the same setup wizard before review side effects. On non-TTY runs, those commands fail fast and point back to cure setup plus cure doctor so a human operator or approved automation can complete setup.

On an interactive cure pr cold start with no existing CURe-managed base cache for the selected baseline, CURe may also ask whether you already have a matching ChunkHound workspace/config for that exact repo. If validation passes, CURe hot-starts the managed base cache from that workspace before running the normal top-up index. Non-TTY runs skip this prompt and build the baseline cache normally.

That indexed ChunkHound-backed path is the default and recommended public review workflow.

cure doctor --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new
cure resume <session_id|PR_URL>

Once the first run is active, continue the same indexed session with cure resume <session_id|PR_URL>.

cure pr --no-index remains available only as an advanced opt-out for custom prompt flows that intentionally skip the built-in ChunkHound-backed prompts. It is not the normal or recommended path.

Review output toggles:

• Verbose final finding cards are now the default for cure pr. They include severity/impact, likelihood, assumptions, downgrade factors, code trail, and reproduction detail. Use --wtf off when you need the older concise finding format.
• Chain-of-Draft hypothesis ledger triage is enabled by default for multipass cure pr runs. It asks step reviewers to record compact candidate issue threads before promoting only grounded survivors into findings. Use --cod-ledger off to disable it; it remains intentionally outside single-pass prompt families.

Built-in CLI-provider review runs use a staged CURe-managed ChunkHound helper rather than native agent MCP wiring. CURe exports that helper through CURE_CHUNKHOUND_HELPER; the built-in prompt/proof contract is per-template successful helper execution whose captured output contains the final structured output for that call, even if preflight/progress lines appear before it. A successful "$CURE_CHUNKHOUND_HELPER" search ... call proves the search requirement. A successful "$CURE_CHUNKHOUND_HELPER" research ... call proves code_research only for templates where that requirement is required or conditional; it remains optional guidance for initial plan and resume-plan. For search, that output may be a JSON object with a results list or a markdown/text block. Per-template contracts decide whether helper research is required, guidance-only, or conditional. Initial plan and resume-plan prompts require helper search but do not require helper research/code_research. Other built-in prompts may still require or conditionally request helper research. Plain chunkhound search, chunkhound research, and chunkhound mcp shell usage are not the built-in CLI-provider contract. Historical sessions may still report legacy mcp_tool_call evidence.

Helper-backed Codex runs also export PYTHONSAFEPATH=1 so a ChunkHound daemon started while reviewing the chunkhound repo does not import the checked-out repo package by accident. If helper preflight times out, inspect the persisted helper path plus daemon lock/log/runtime metadata in session status or meta.json before retrying.

Codex executor paths need internet / network access to obtain code-under-review context. In constrained agent sandboxes, treat that as an operator-visible prerequisite and ask for help instead of claiming CURe can guarantee end-to-end setup or runtime access. When cure doctor resolves Codex, look for the executor-network advisory check instead of claiming the sandbox already proved that prerequisite.

Codex explicit override example:

cure doctor --llm-preset codex-cli --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new --llm-preset codex-cli

To persist the choice for future runs, use cure set-agent codex after the operator has approved Codex as the local CLI provider. cure setup can repair missing non-secret bootstrap files and the saved local-agent choice only when the selected config target is approved and the choice is unambiguous.

Need the full operator-controlled setup checklist for agent sessions or existing local setups? Use SKILL.md.

Core Commands

Recommended indexed review loop:

cure doctor --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new
cure resume <session_id|PR_URL>

Initialize or repair non-secret bootstrap files:

cure setup

Start a fresh review:

cure pr <PR_URL> --if-reviewed new

Check status:

cure status <session_id|PR_URL> --json

Watch a run:

cure watch <session_id|PR_URL>

Resume a session:

cure resume <session_id|PR_URL>

Clean up old sessions:

cure clean closed --json
cure clean <session_id>

Show the machine-readable command catalog:

cure commands --json

Secondary Standalone Install

The public package remains the default and recommended path:

uv tool install cureview

Use the standalone GitHub Release assets only when the package path is unavailable or inconvenient, and only when the operator has approved running the installer in the current environment. The current secondary targets are:

• Linux x86_64 with glibc 2.31 or newer
• macOS x86_64
• macOS arm64

Install the latest standalone release:

curl -fsSL https://raw.githubusercontent.com/grzegorznowak/CURe/main/install-cure.sh | sh

Pin a specific standalone release:

curl -fsSL https://raw.githubusercontent.com/grzegorznowak/CURe/main/install-cure.sh | sh -s -- --version v0.1.8

The installer downloads the matching release asset into ~/.local/bin/cure. Agent sessions should not run this installer just because package installation failed; they should stop unless the operator approves this persistent install path. After that, the bootstrap/readiness flow is unchanged:

cure setup
cure doctor --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new

If your platform is not covered by the standalone assets, fall back to the package path instead of inventing a separate bootstrap recipe.

Advanced / Pre-Provisioned Environments

Persistent human install should use the public package:

uv tool install cureview
cure setup
cure doctor --pr-url <PR_URL> --json
cure pr <PR_URL> --if-reviewed new

Teams that already manage a local CURe checkout can keep using that as a secondary local-development flow:

• keep CURe in a stable local path
• refresh it with git -C <CURE_SOURCE> pull --ff-only
• install it with uv tool install /path/to/cure
• keep any project-specific wrappers or config beside that checkout

If local CURe config already exists, inspect it before overwriting it:

• check the active cure.toml
• inspect the JSON resolved from [chunkhound].base_config_path
• treat repo-root chunkhound.json or .chunkhound.json as setup hints to discuss with the operator, not inputs to silently adopt

Prefer cure doctor --pr-url <PR_URL> --json as the readiness summary after that inspection. It now reports repo_local_chunkhound plus the repo-local-chunkhound and executor-network checks so the operator does not need to infer those details from raw files alone.

When no explicit preset or config default is selected, CURe autodetects codex-cli from the high-confidence session markers it already understands. If autodetect needs to be overridden, pass --llm-preset codex-cli explicitly.

Those details are secondary. The primary operator contract stays use <CURE_REPO_URL> to review <PR_URL>.

Example: use https://github.com/grzegorznowak/CURe to review https://github.com/chunkhound/chunkhound/pull/220. That sentence is the kickoff contract, not a promise that every sandbox can finish setup unattended. The operator should not need to provide a local checkout path. It should not do a manual review outside CURe.

For the full operator-controlled checklist around approved installs, existing local setup, and operator handoff, use SKILL.md.

Minimal Config

Default config path:

~/.config/cure/cure.toml

By default cure setup also writes:

~/.config/cure/chunkhound-base.json

If you need a disposable or non-default layout, set XDG_CONFIG_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME before cure setup, or pass --config, --sandbox-root, and --cache-root directly to cure setup.

Minimal config written by cure setup:

[paths]
sandbox_root = "/absolute/path/to/sandboxes"
cache_root = "/absolute/path/to/cache"

[review_intelligence]
[[review_intelligence.sources]]
name = "github"
mode = "auto"

[[review_intelligence.sources]]
name = "jira"
mode = "when-referenced"

[chunkhound]
base_config_path = "/absolute/path/to/chunkhound-base.json"

[multipass]
# strict = fail closed on invalid grounding
# warn   = record findings and continue
# off    = skip grounding validation
grounding_mode = "strict"
step_workers = 4

[llm]
# One execution effort now applies to plan, step, and synth.
reasoning_effort = "high"

On interactive cure pr runs, CURe can open a /dev/tty picker for the resolved CLI provider when model or execution reasoning_effort was not explicitly configured. Press Enter keeps the displayed defaults. Built-in Codex defaults are explicit: codex-cli defaults to effort high.

When strict multipass grounding fails, CURe keeps the invalid artifact on disk and writes the validation details to work/grounding_report.json inside the session. Inspect the persisted state with cure status <session_id|PR_URL> --json or cure watch <session_id|PR_URL>, then rerun the same session with cure resume <session_id> or the narrower cure resume <session_id> --from steps / cure resume <session_id> --from synth. If you want fail-open behavior for future runs, set [multipass].grounding_mode = "warn".

If an embedding key is already present in the environment, cure setup adds the matching non-secret embedding provider/model block and continues. If VOYAGE_API_KEY already exists, cure setup writes the Voyage embedding model into the active ChunkHound base config and continues. Otherwise, if OPENAI_API_KEY already exists, cure setup writes the OpenAI embedding model into the active ChunkHound base config and continues. CURe does not write the secret value into that config.

If no supported key is present, an assisting agent should stop with the exact local config path, the minimal snippet to add, the required env var name, and the rerun command instead of improvising a manual review. Agents must not ask the operator to paste secret values into chat, infer secret values, or persist secrets outside operator-approved local mechanisms.

The structured review_intelligence source registry now feeds prompt guidance, session metadata, and cure doctor --json capability summaries. Only mode = "required" sources are preflighted before review generation; optional sources stay lazy and surface as available, unavailable, or unknown based on the runtime facts CURe already has.

Jira CLI

Use this only when the workflow actually needs Jira context. Normal public GitHub PR review flows do not require Jira.

For tenant setup, auth, jira init, JIRA_CONFIG_FILE, common queries, and troubleshooting, use the dedicated Jira reference.

If Jira context is required in a CURe session, keep auth local, prefer ~/.netrc for api.atlassian.com or a short-lived JIRA_API_TOKEN, and point CURe at a non-default Jira CLI config with JIRA_CONFIG_FILE when needed.

Tests

Fast local check:

./selftest.sh