Corvint

A Beamfall project.

Context your agents can cite. Changes your reviewers can check.

Corvint is a local-first context compiler for coding agents. Before an edit it hands the agent Git-pinned evidence with the reason each item is there. After the edit it binds every diff hunk to cited evidence, an explicit unknown, or a verifiable mechanical exception, in a portable sidecar that CI checks without an LLM.

Install · Workflow · Status · Documentation

One native Go binary. No account, hosted service, database, embeddings, or permanent daemon. go.mod declares no module requirements. Read commands do not mutate repository or trace state; the two bounded exceptions are a local .corvint/self-observations.jsonl ledger and, only while the operator marker .corvint/unplanned-reads.enabled exists, .corvint/unplanned-reads.jsonl — neither is a direct input to ranking, evidence, or authority. Learning from these ledgers requires an explicit operator step and a frozen held-out gate (AGENTS.md invariant 4). Version 1.0.0-rc.2 is the next release candidate for Corvint 1.0, and 1.0.0-rc.1 is the published prerelease; what 1.0 promises and what is still being qualified.

Why Corvint

Finding relevant text is only part of a coding task. An agent also needs to know which document governs the change, which tests constrain it, and what evidence is missing. A reviewer needs to follow those decisions back to their sources.

Corvint makes that evidence inspectable through context receipts and a map beside the diff.

• Every result explains itself. Each item in a packet carries the Git blob it came from, the path and line, the authority that admitted it, a confidence level, and a plain-language inclusion reason. A reviewer can follow any citation to immutable content.
• Your repository is the authority. Agent instructions, accepted decisions, and specs you already keep outrank syntax matches, history correlations, and learned traces. Corvint uses the documents you have; it introduces no new spec language.
• It says what it does not know. Coverage, omissions, uncertainty, and freshness are fields in the receipt, and a hunk without cited evidence is an explicit unknown. Task-level retrieval abstention is experimental and unqualified; see Status.
• Reviewers get a disposition for every hunk. A Change Evidence Map (CEM) links each textual hunk of a diff to cited evidence, an explicit unknown, or a mechanical exception. The verifier checks patch, hunk, blob, and span identity locally, with no LLM, no index, and no shared service. The protocol is Apache-2.0, so anyone can implement or verify it.
• Local and explicit. The core reads Git and prints JSON. Default evidence flows make no network call. query, context, impact, affected, and non-executing prove modes report mutates: false, subject to the private-ledger exceptions above. record explicitly retains task outcomes; learning stays local, bounded, secret-screened, and evaluation-gated.

Sixty seconds on this repository

You need Git and Go 1.27.1 or later; the full development gate pins exactly go1.27.1. Run this from the root of a Corvint checkout on macOS or Linux:

GOTOOLCHAIN=local go run ./cmd/corvint impact cmd/corvint/main.go --limit 5

That asks what a change to the CLI entry point could affect. The receipt names the requested path, the tests that constrain it, the reason each result was admitted, and what the result limit left out. No installation or account is needed. Abridged output captured from public commit f51f3c9e6fbfc5a6b219692e8bf46e4e43297a36 with its source-built CLI (fields, results, and evidence records omitted; shown values unchanged). Your checkout determines the hashes and counts:

{
  "context": {
    "results": [
      {
        "id": "cmd/corvint/main.go",
        "kind": "path",
        "evidence": [
          {
            "authority": "git-tree",
            "blob_hash": "3f1a1e9e858b7531c186ad05e42cde01c9d87222",
            "confidence": "authoritative",
            "line": 1,
            "path": "cmd/corvint/main.go",
            "reason": "requested changed path"
          }
        ]
      },
      {
        "id": "cmd/corvint/main_test.go",
        "kind": "test",
        "evidence": [
          {
            "authority": "test-convention",
            "blob_hash": "1b757630da987860fd3b2d321981d8fc6f09dcca",
            "confidence": "high",
            "line": 1,
            "path": "cmd/corvint/main_test.go",
            "reason": "same-package test for cmd/corvint/main.go"
          }
        ]
      }
    ],
    "freshness": {
      "revision": "099c102b26602c83ec91a9f8f7eb7491e0b3f040",
      "scope": "git",
      "state": "fresh"
    },
    "coverage": {
      "included_results": 5,
      "omitted_results": 267,
      "uncertainty": [
        "267 ranked results omitted by result limit"
      ]
    }
  },
  "mutates": false,
  "tool": "impact"
}

Install the binary to use Corvint in any supported Git repository:

mkdir -p "$HOME/.local/bin"
GOTOOLCHAIN=local go build -ldflags "-X main.build=$(git rev-list --count --first-parent HEAD)" -o "$HOME/.local/bin/corvint" ./cmd/corvint
export PATH="$HOME/.local/bin:$PATH"
corvint --version

Versioned assets are on the releases page. The Core rc.1 release contains only corvint, with four macOS/Linux archives, SHA256SUMS and verification-report.json. A matching native archive needs Git but no Go compiler; verify both the downloaded archive and its internal checksums before running it. Read the exact platform's qualification, including native versus emulated runs. Tasks has its own developer release; source companions are not automatically included in a Core archive. Source builds report 1.0.0-rc.2; until that candidate is published, rc.1 is the newest Core release. Like rc.1, rc.2 and 1.0 are unsigned: SHA256SUMS only, publisher identity NOT_VERIFIED (decision 0433). The installation guide covers checks, first use, optional tools, upgrades and removal.

The workflow

Replace src/session.py with a path tracked in your repository. Go, Python, and JS/TS have reverse-import impact rules; other indexed languages do not all receive equivalent analysis. corvint COMMAND --help prints each command's contract. To select a repository explicitly, put --root /path/to/repo before the command.

The experimental features, overview, and review commands require a clean tree and expose inferred scope, omissions, and unsupported cases. They do not accept requirements or execute suggested commands. review requires a full ancestor base SHA and does not replace CEM or tests.

Give the agent a useful next step

A context packet can identify a test counterpart and say why it matters. From the session-revocation fixture (fields omitted; values unchanged):

{
  "id": "src/test_session.py",
  "kind": "pair",
  "action": "Update this test: it is the subject's test counterpart, so a behaviour change in the subject changes what it must assert.",
  "evidence": [{
    "authority": "test-convention",
    "confidence": "high",
    "blob_hash": "50404716f6d80b4cbfc88c61529c78bd748250c4",
    "reason": "test counterpart of src/session.py"
  }]
}

After src/session.py is edited, prove reports mixed-worktree freshness and names the changed path. Trace recording is blocked for that mixed state. The receipt keeps working changes apart from committed evidence, so the agent and the reviewer can see the difference.

Put the evidence beside the diff

A Change Evidence Map is a portable sidecar that travels in the repository and verifies with no LLM, no index, and no shared service. For a committed change, replace BASE_SHA with its base commit and the example citation with a span that exists at that base:

corvint cem prepare --base BASE_SHA --target HEAD
corvint cem cite --map .corvint/change.cem.json --hunk 1 \
  --evidence-path docs/decisions/0001-session-revocation.md --lines 5:5 --relation decision
corvint cem status --map .corvint/change.cem.json \
  --expected-base BASE_SHA --target HEAD --max-unknown 0 --max-mechanical 0

For a one-hunk change, prepare produces an incomplete worklist; after the citation, status reports "state": "ready-for-ci" with a stable span. A larger diff needs a disposition for every hunk, and the worklist says what remains. The policy above permits no unknowns and no mechanical exceptions. CEM in CI wires that policy into a pipeline.

The nextActions argv that cem prepare and ocm prepare return starts with the command name corvint. Run it with a corvint binary in that first position, or build one under that name (go build -o corvint ./cmd/corvint).

The verifier proves structural integrity: patch, hunk, blob, span, and mapping identity. It does not prove semantic support, causality, test adequacy, or program correctness, and Corvint says so. The wire format, schemas, and conformance vectors are Apache-2.0.

Optional Go LSP evidence

The following CLI/MCP selectors are newer than the published Core rc.1 binary and are present in 1.0.0-rc.2 source builds. Build the current source and matching MCP companion, or check your installed corvint help context before using them.

Corvint can use gopls, the Go language server, to add definition and reference relationships to a context packet. This integration is experimental and opt-in; it does not change ranked results or project authority. Install gopls explicitly and have your workspace dependencies available locally, then select a tracked Go file (here, in Corvint’s checkout):

corvint context --task "Find callers and dependencies" \
  --subject cmd/corvint/main.go --lsp gopls

Use --lsp off to disable enrichment, including when the legacy environment setting enables it. For MCP, start corvint-mcp with --tool-profile task-review-lsp and pass "lsp": "gopls" to corvint.context; omitting that argument starts no language server. Other MCP profiles do not enable LSP. See the Go LSP guide for installation, full CLI/MCP examples, limits, qualification, and troubleshooting. Other language servers are outside this milestone.

Works where agents work

The host adapters run corvint from PATH, so install it there first. Core lifecycle adapters report FALLBACK (compatibility matrix). The optional OpenCode native integration has a separate exact-tuple qualification; its integrationSupport: FULL does not confer execution or closing Frontier authority (OpenCode support). The Codex and Claude Code adapters are Core host rows; Gemini CLI, OpenCode and Pi are companions:

• Codex, Claude Code, Gemini CLI, OpenCode, and Pi share one bounded lifecycle receipt (corvint help harness event).
• VS Code, deferred and not part of 1.0: evidence views plus opt-in automatic unit/E2E reruns on editor saves. Install the VSIX and providers, configure the project's toolchains and suite, then enable corvint.liveTests.enabled. It reruns the configured suite; passing tests do not establish test adequacy or authority. Setup and stop instructions.
• MCP: corvint-mcp is a companion local stdio server that exposes read-only receipts (GOTOOLCHAIN=local go build -o ./bin/corvint-mcp ./cmd/corvint-mcp). corvint-docs-mcp drafts source-bound documentation and checks a draft against source; corvint-test-validity-mcp lets agents inspect retained test observations. Both need a compatible client and an explicit root; setup and boundaries.
• Source-bound documentation: the companion docs maintain --watch command refreshes a generated page block as eligible source commits land, preserves surrounding prose, and stops on outside page edits. It runs explicitly in the foreground on macOS/Linux with time and write limits; preview, apply, and watch.
• The workflow tools below: tickets, dashboard, console, test providers and release checks. Optional Tasks supervision and dispatch start only through explicit operator configuration; they have their own qualification and process-lifecycle limits.

Corvint uses the corvint-* wire/profile namespace, corvint.* MCP tools, and canonical .corvint and .context-corvint repository paths. Those are protocol and state contracts and are versioned independently of the product. The frozen minimum CEM wire is cem/0.2 with an N-1 cem/0.1 reader. The separate experimental cem/0.3 adds structural mechanical reasons and optional test witnesses; it is not the default Core sidecar or a new stability claim (profile boundaries).

The rest of the toolbox

The core CLI works on its own. Separately packaged tools expose test results, tickets, and evidence; some also run tests, supervise agents or perform explicit local writes. They are qualified separately from Core and do not inherit its stability promise. Selected Flows, Tasks, documentation and MCP outcomes are required for stable 1.0 promotion (expanded scope).

corvint-console --repo /absolute/path/to/repo --tasks /path/to/corvint-tasks \
  --snapshot /path/to/corvint-dashboard-snapshot

go build -o /tmp/corvint-lsp ./cmd/corvint-lsp
/tmp/corvint-lsp --experimental --gopls /absolute/path/to/gopls --root /absolute/project/root

Built to be checked

Status, stated plainly

[!IMPORTANT] 1.0.0-rc.1 is the published release candidate for Corvint 1.0, and 1.0.0-rc.2 is the next candidate, not yet built or published. The 1.0 stability promise (frozen contracts, N-1 readers or deterministic migrations) covers the Core surfaces below and nothing else (1.0 scope, decision 0373). Stable 1.0 also requires the expanded Flows, safe navigation, documentation/MCP, full Beamfall roadmap takeover by Tasks and automatic documentation outcomes accepted in decision 0426. Those requirements do not expand Core's binary boundary or transfer its stability promise to companions. The three Core jobs must pass on Corvint, Beamfall and one untouched public repository (PRS-V1-008; urfave/cli for rc.2, decision 0432), alongside the expanded product qualification. Platform status comes from each release's exact assets and evidence. The table distinguishes retained rc.1 evidence from the expanded scope; it does not qualify later source changes.

These boundaries are backed by committed artifacts: the 1.0 scope, the release notes, the specification index, and benchmarks/.

Read next

• Documentation and repository layout: current guides and source organization
• Product contract: the job, trust boundary, and measurable product loop
• Architecture: how the pieces fit
• Agent evidence routes: task-sized paths to authority, code, tests, and next action
• Specification index: accepted intent versus actual delivery state
• Change Evidence Map: the interchange contract
• CEM in CI: wiring the verifier into a pipeline
• Dogfood contract: how Corvint must prove substantive Corvint changes

Development

For a scoped change, use corvint affected --base FULL_BASE_SHA, retain its unknowns, then run focused tests and the checks required by the owning contract. Follow the dogfood contract and obtain independent review. Release or repository-wide validation uses the exhaustive gate below, which includes root tests/vet, interoperability, archive and documentation checks:

test "$(GOTOOLCHAIN=local go env GOVERSION)" = "go1.27.1"
GOTOOLCHAIN=local make gate
script/release-checklist      # read-only; PASS/FAIL/NOT_RUN, exits 0 only when all required rows pass

Standalone root or interoperability tests use go test -count=1 -timeout 30m ./... and go vet ./... in the corresponding module with GOTOOLCHAIN=local. The 30-minute limit is a per-package hang detector. Do not rerun the same checks before make gate unless changed inputs or a failure require it.

If GOTOOLCHAIN=local go env GOVERSION reports a different patch version than go1.27.1 (for example, a Homebrew go formula upgrade changed the linked toolchain), install the exact pinned version alongside it rather than relinking Homebrew's default, then prepend its bin directory to PATH for gate commands only, e.g. PATH=/opt/homebrew/Cellar/go/1.27.1/bin:$PATH GOTOOLCHAIN=local make gate (Intel Homebrew: /usr/local/Cellar/go/1.27.1/bin).

Gemini/OpenCode adapter tests use their hosts' Node runtime. Core builds and the native regression suite do not require Python; optional qualification scripts, such as the live Go LSP campaign, may require Python 3 and their declared external tools. See native regression ownership.

License

Corvint is free software under the GNU Affero General Public License v3.0 or later. The portable protocol descriptions, schemas, conformance material, examples, and interop implementations are Apache-2.0 instead, so anyone can implement the standard, including in proprietary software, without the copyleft attaching. See LICENSING.md for the exact path boundary, LICENSE for the AGPL text, LICENSE-APACHE-2.0 for the Apache text, and PROVENANCE.md.