codecrucible

name	codecrucible
description	Use CodeCrucible to run, configure, troubleshoot, or interpret LLM-backed security scans and SARIF output. Use when a user asks to scan a repository with codecrucible, choose a provider/model or prompt set, estimate scan cost, inspect phase artifacts, automate a scan, or explain CodeCrucible findings. Do not use for general security review requests that do not involve CodeCrucible.

CodeCrucible

Use CodeCrucible as a cost-aware security scanning CLI. Treat its output as evidence to verify against source, not as a final vulnerability verdict.

Workflow

1. Identify the target repository, requested scope, output destination, and whether the user wants an exploratory scan or a CI gate.
2. Read the target repository's agent instructions before scanning it.
3. Inspect the CodeCrucible repository docs before choosing flags:
   • Read README.md for CLI flags, provider setup, config precedence, and built-in supported models.
   • Read PROMPT_SETS.md when choosing a prompt set.
   • Run ./codecrucible list-models --provider <provider> when credentials are configured and provider-reported endpoints matter; do not invent model IDs or provider-specific parameters.
4. Use ./codecrucible from the repository root when the binary exists. Run make build first when working from a fresh checkout.
5. Start with a dry run unless the user explicitly asks to execute immediately:

./codecrucible scan /path/to/repo --dry-run

6. Review the dry-run scope, token estimate, and cost estimate. Narrow with --paths, --include, or --exclude when the scan is broader than the user's request.
7. Run the real scan with an explicit output path and preserve phase artifacts when analysis or troubleshooting matters:

./codecrucible scan /path/to/repo \
  --output /tmp/codecrucible-results.sarif \
  --phase-output-dir /tmp/codecrucible-phases

8. Verify reported findings in source before presenting them. Distinguish the final audited SARIF from pre-audit analysis artifacts.

Selection Guidance

• Use prompts/default for general first-pass coverage.
• Use the closest prompts/exploit-proof-* set for language-specific, precision-oriented reviews.
• Use prompts/exploit-proof for polyglot targets or when no language-specific set fits.
• Use carlini, carlini-curated, or nano-analyzer only when the user asks for that style or when the constraints described in PROMPT_SETS.md fit the task.
• Prefer cheaper models for feature detection and stronger reasoning models for analysis when cost matters; use per-phase flags instead of forcing one model across every phase.
• Keep --max-cost set for exploratory work. Use --fail-on-severity only when the user wants a gating exit code.

Provider And Config Rules

• Keep API keys in environment variables; do not put them in commands, config files committed to git, or responses.
• Respect config precedence: CLI flags override environment variables, which override config files, which override defaults.
• For custom or newly released models, inspect README.md, internal/config/models.go, and provider documentation before setting context limits, output limits, structured-output flags, or model params.
• If a model or provider is unknown to the built-in registry, use explicit --context-limit and --max-output-tokens rather than assuming defaults are correct.

Reading Results

• The main --output file is the final SARIF result after audit when audit is enabled.
• *.analysis.sarif is the pre-audit finding set.
• *.audit.sarif shows the audited result.
• *.feature-detection.json helps explain why sections were included or pruned.
• When a finding disappears between analysis and audit, inspect the audit artifact before concluding the scanner missed it.
• When reporting findings, include file path, line, CWE/rule ID when present, exploitability reasoning, and whether the finding survived audit.

Common Commands

# Query provider-reported models/endpoints when credentials are configured.
./codecrucible list-models --provider anthropic

# General scan with a precision-oriented Go prompt set.
./codecrucible scan /path/to/repo \
  --prompts-dir prompts/exploit-proof-web-go \
  --output /tmp/codecrucible-results.sarif

# Cost-aware mixed-model scan.
./codecrucible scan /path/to/repo \
  --fd-provider google --fd-model gemini-3.5-flash \
  --provider anthropic --model claude-opus-4-8 \
  --audit-provider anthropic --audit-model claude-sonnet-5 \
  --max-cost 25 \
  --output /tmp/codecrucible-results.sarif