Skip to content
CodeVetter docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

The native verification workbench and its shared CLI and MCP contracts.

Surfaces and navigation

The native app uses one persistent macOS split-view shell. Every page shares the same header, content width, spacing scale, evidence language, loading/empty/error treatment, and keyboard-sized click targets.

Section Native source Primary result
Explore NavigatorWorkspaceView.swift Read-only Git source, fuzzy file search, indexed search, declarations, history, and integrated Unpack.
Review NavigatorWorkspaceView.swift, PremiumWorkbench.swift Pinned GitHub/local diffs and exact source links, alongside the existing executable verification and handoff receipts.
Testing PremiumTestingView.swift plus focused testing views Preview, changed verification, scenarios, differential runs, warm verification, and opt-in PR watchers.
Performance PremiumPerformanceView.swift Exact local workload, baseline/candidate measurements, limits, cleanup, and optimization verdict.
Runs PremiumInvocationRunsView.swift, PremiumWorkbench.swift Explicit skill invocation history and integrity inspection; saved verification receipts remain separate.
Settings PremiumSettingsView.swift Accounts, agents, MCP, rubrics, memories, history roots, updater/about, and other configuration.

The app source lives in apps/macos/CodeVetterPackage/Sources/CodeVetterFeature/. ContentView.swift owns navigation; PremiumPageHeader.swift and EvidenceStyle.swift own the shared page grammar.

Synchronized interfaces

The native UI uses the bundled codevetter executable. Humans and agents can call the same CLI directly, while codevetter-mcp publishes bounded read-only projections. Rust-owned schema versions and semantics are shared across all three; the SwiftUI client does not reimplement verdicts.

Typical entry point:

codevetter check --range main...HEAD \
  --task "Describe the expected behavior" \
  --json

Supporting commands cover scope resolution, T-Rex testing, performance, differential verification, scenario compilation, Repo Unpack, settings, rubrics, memories, MCP readiness, X-Ray export, and isolated fix attempts. Run codevetter --help for the exact current contract.

MCP remains read-only: it can inspect evidence and prepare bounded review context, but it cannot start a review, execute tests, approve a fix, alter settings, or publish anything.

Advisory ordering and optional feedback

Testing scope plans carry check_priority ordinal points and source-backed factors. Relevance and exact target selection dominate this tie-breaker before the 12-target cap. Reads are bounded; missing source and downstream reach stay explicit. Dirty or mismatched-head checkouts disable content priority. Performance ordering is unchanged. Priority is scheduling advice, never a correctness verdict, defect probability, or approval. Preflight and saved checks preserve the selected plan and candidate in correctness_selection; an explicit target retains explicit selection authority.

Attach caller-reported outcomes to an existing persisted local-check run:

codevetter outcomes --operation record --repo /absolute/repo --run-id <run-id> \
  --event-id incident-42 --kind incident --group-id production-42 \
  --reason "Regression reproduced" --evidence-ref "issue:42" --json
codevetter outcomes --operation list --repo /absolute/repo --run-id <run-id> --json
codevetter outcomes --operation summary --repo /absolute/repo --run-id <run-id> --json

revert can share the incident’s --group-id so the adverse event counts once. confirmed_safe requires --basis; human_override requires --action accept|reject|defer and is counted separately. Every record requires a bounded reason, evidence reference, and unique event ID. Identical retries are idempotent; conflicting retries fail. At most 1,000 events attach to one run. The append-only ledger binds the exact stored receipt digest, repository, full base/head, source mode, and source input. Replaced receipts fail closed. Labels never rewrite the canonical receipt, change approval, or train a model. verification_get_receipt exposes a bounded caller-reported summary, record count, and receipt digest as a separate read-only MCP sibling; use CLI list for full records. Unavailable feedback leaves the receipt readable. The sibling is omitted when it would exceed the response budget of an otherwise readable receipt; absent feedback does not mean there are no recorded outcomes.

Optional wording uses an explicitly selected local OpenAI-compatible endpoint:

codevetter explain --repo /absolute/repo --run-id <run-id> \
  --endpoint http://127.0.0.1:1234/v1 --model local-model --json

Only completed, ready reviews and canonical source-qualified final findings are eligible. The request contains opaque IDs and original title, description, and suggestion text. Paths, anchors, severity, and other receipt metadata are not added to the payload. Literal HTTP loopback, the exact /v1 path, no proxy, no redirects, bounded bytes, and a 15-second total deadline constrain one request without retries. Invalid canonical identities, oversized individual findings, or excessive finding counts fail with an input error. An oversized aggregate request, invalid model output, or network failure preserves original wording without changing canonical evidence. wording_verified is always false. Provider-reported tokens and actual duration are separate from unknown cost; no savings are claimed. These optional CLI operations add no native controls or MCP execution authority.

Agent usage ownership

The general agent-usage dashboard and provider allowance checks have moved to ContextDaddy. CodeVetter no longer exposes a Usage workspace or general codevetter usage/codevetter quota commands. Token and cost evidence attached to an individual verification run remains in its receipt and Runs ledger. CodeVetter’s History settings and history-roots command are retained for its existing local evidence archive and are not a general usage dashboard.

If you used codevetter usage or codevetter quota in a script, move that workflow to ContextDaddy’s app. ContextDaddy has no equivalent CodeVetter CLI command; these retired commands now return a migration message instead of a usage or quota receipt.

Interaction policy

Review and Explore navigation

After opening a local repository in Review, the comparison bar exposes Review branch and Compare against using local and available remote-tracking refs. Local changes initially shows the worktree against HEAD; choosing two branches and Show diff resolves their merge-base/head without checkout or fetch. Pending selections cannot start a review. Refresh preserves the applied selection; opening another repository clears the previous comparison and verification plan.

Review change… opens the existing setup with the exact displayed commit pair, review instructions, reviewer choice, Plan, and Run review & checks. The range is read-only there; Change comparison returns to the browser. Plan does not execute repository code. Executable verification still requires a clean checkout at the selected head: uncommitted changes remain inspectable, not silently converted into a different review range. Imported PR/commit comparisons stay pinned; repository/file URLs without a base remain source-only. The local repair is tracked in #285, not yet released.

The landing surface accepts public GitHub repository, PR, commit, branch, and file URLs, or a local repository. The Rust navigator pins commits and blobs; PRs use their merge base. Source opens before background indexing. Cmd+P finds files, Shift+Cmd+F searches indexed text, and Shift+Cmd+O lists JavaScript/TypeScript declarations. The source plane renders visible rows from bounded Rust windows. Unified and split diffs retain old/new line numbers; full-source and base/head views share the same pinned identity.

Unpack is available beside source. Its deterministic map links repository instructions, architecture documents, manifests, entry points, and imports to their files. Existing reports at the matching revision add subsystem claims, workspace modules, and decision sources. Imported text snapshots can be handed to the existing Unpack scan without executing repository code. Coverage exclusions remain explicit. Findings and recorded runtime stack locations open inside CodeVetter at the receipt revision, never through the default editor.

The navigator has a separate in-process library boundary; verification remains on the existing CLI/receipt boundary. See the navigator implementation and tracking issue #285. Double-click, F12, and the source context menu use bundled TypeScript 7.0.2 semantic definitions; Shift+F12 finds references. Left/right arrows move the symbol position and up/down arrows move source lines. Rust runs the native LSP worker against separate base/head source snapshots with admitted compiler configuration, including path aliases. Its macOS sandbox denies outside reads, writes, subprocesses other than the worker itself, and network access. It never installs dependencies or runs repository code. External packages and unsupported languages remain outside semantic coverage; file browsing and literal search continue independently. The declaration list remains syntax-backed. Text indexing and semantic snapshots are bounded to 32 MiB, individual indexed files to 2 MiB, and source reads to 64 MiB; excluded content is never reported as indexed. Git history is limited by available fetched history. Refreshing explicitly replaces a local source snapshot; a drifted local diff is rejected. In-process benchmark timings do not establish keyboard-to-pixel latency or foreground interaction qualification.

Verification policy

Repository selection is shared across Explore, Review, Testing, Performance, and Settings. Choosing a different repository clears repository-specific setup, including preview URLs, comparison inputs, and performance targets; browsing opens the new source when resumed. Reselecting the same folder preserves setup. Unpack details beside source require both the repository and revision to match.

Testing can copy the applied Review comparison; pending branch selections are not accepted. Browser execution still requires an explicit preview URL and fresh confirmation. Performance exposes target discovery before manual workload fields. Saved-result links select the originating run, or explain when it is outside the latest 50 saved runs. Settings refreshes the currently selected section’s data.

  • Review findings are leads until executable evidence supports a verdict.
  • Watchers are opt-in and app-lifetime bounded; they do not run while the app is closed and each execution session requires consent.
  • Destructive cleanup, fix execution, and authority changes are explicit, separately confirmed operations.
  • Missing usage, provider quota, or runtime data remains visibly unavailable.
  • Settings is one coherent destination with subsections, not a collection of unrelated top-level pages.

The retired React routes and Tauri WebView are historical implementation details. Do not restore them as parallel product surfaces.

Was this page helpful?