falsegreen

Independent verification for coding agents.

FalseGreen gives your AI coding agent an independent completion-authority loop. When the agent says "I'm done," FalseGreen runs your frozen acceptance criteria against an immutable source snapshot and tells the agent whether the work actually passes — instead of trusting the agent's own self-assessment.

This crate is the client shim — a tiny native binary that:

• speaks STDIO MCP to your coding agent (Codex, Claude Code, Cursor, etc.)
• authenticates to the FalseGreen service with your API key
• snapshots the active local workspace before source-sensitive tools
• forwards tool calls over HTTPS to mcp.falsegreen.com
• manages device activation and credentials locally

The actual verification engine lives server-side. This binary contains no verification logic.

Install

cargo install falsegreen

Quick start

# 1. Log in (activates this device with your Polar license key)
falsegreen login --token YOUR_FALSEGREEN_KEY

# 2. Install into your agent
falsegreen install codex           # Codex CLI & Codex in VS Code (STDIO)
falsegreen install github-copilot  # GitHub Copilot in VS Code (local STDIO)
falsegreen install claude-code     # Claude Code (local STDIO)
falsegreen install opencode        # OpenCode (local STDIO)
falsegreen install cursor          # Cursor (local STDIO)

# 3. Verify
codex mcp list   # for Codex

The agent launches falsegreen mcp locally so it can snapshot the workspace before forwarding each source-sensitive operation.

How it works

Coding agent (Codex, Claude Code, Cursor, ...)
  │
  │ STDIO MCP (JSON-RPC over stdin/stdout)
  ▼
falsegreen  ← this binary
  │
  │ workspace snapshot upload + MCP calls (HTTPS + X-API-KEY)
  ▼
mcp.falsegreen.com
  │
  ├─ validate API key via Polar (cached 5 min)
  ├─ check per-tenant rate limit
  ├─ resolve tenant state directory
  └─ run verification engine
        │
        ├─ materialize the uploaded workspace source
        ├─ snapshot an immutable source artifact
        ├─ execute frozen acceptance criteria
        └─ return accepted / incomplete / unsafe

Verification artifacts

Every completed run with a retained source snapshot produces two stable files:

• falsegreen-attestation.json is canonical machine-readable evidence using schema falsegreen.attestation/v1.
• falsegreen-report.md is a concise report suitable for attaching to a pull request. FalseGreen does not post it to GitHub automatically.

Retrieve both with falsegreen_get_verification_artifacts. The optional run_id selects a historical run; otherwise the task's latest completed run is used. The response includes both artifacts inline, their filenames, status, source digest, and signing status.

Execution provenance is captured automatically for supported runtimes. Python commands retain the interpreter version. Cargo and rustc commands retain Cargo and compiler versions, the exact rustc -Vv identity, host target, and tool digests. Ruby, Bundler, Rails, and Rake commands retain the exact Ruby and Bundler versions and executable digests. The compact values are also shown in the Markdown report.

Ruby projects use a frozen Gemfile.lock. FalseGreen downloads the exact RubyGems artifacts in its networked dependency zone, verifies and retains their content manifest, then runs bundle install --local in a networkless build zone. Workspace-local Bundler PATH sources are accepted only when their normalized paths remain inside the immutable source snapshot; their contents are bound by the source digest. Git and plugin sources remain rejected. Verification remains networkless and receives the prepared bundle through BUNDLE_PATH. Rails commands such as bundle exec rails test, bundle exec rake test, and repository binstubs are supported; native gems build against the image's Ruby headers and common database/system libraries.

Go modules are downloaded without compiling repository packages in the network-constrained dependency zone. Verification receives a private module cache and always runs with GOTOOLCHAIN=local, GOPROXY=off, and GOSUMDB=off. Go attestations include the Go version, GOOS/GOARCH, workspace mode, and binary digest.

GNU Fortran and dependency-free fpm projects run offline with gfortran/fpm provenance. Ada projects support GNAT and GPRbuild; dependency-free Alire projects can run offline. Because fpm and Alire do not provide a generally safe fetch-only operation that FalseGreen has qualified, dependency-bearing projects fail closed as unsupported instead of executing package actions with network. SPARK is a distinct method: spark_proof evaluates GNATprove's summary and SARIF artifacts, reports discharged, unproved, and justified obligations, and cannot accept based on process exit status alone.

Downloaded wheels, Cargo files, Ruby gems, Go modules, and frozen external artifacts enter a shared toolchain-bound cache. Exact dependency requests skip resolution and downloads on later runs, while a global SHA-256 object store deduplicates common artifacts across different projects and tenants. Per-run views are read-only hardlinks, expire after one day by default, and can be recreated from shared entries. Size, age, and minimum-free-space policies bound the durable cache; verification build directories remain private and temporary.

Rust/native builds that require publisher release archives can declare external_artifacts in the task contract. FalseGreen freezes each artifact's direct approved HTTPS release URL, SHA-256, byte size, archive handling, and environment-variable binding. The dependency worker downloads only those declared bytes, the controller verifies and safely extracts them, and the build receives the resulting file or directory read-only with network access still disabled. Artifact identity and the retained dependency-manifest digest are included in the signed attestation and Markdown report.

The mandatory source_digest identifies the exact immutable normalized source snapshot that the verifier executed. It is not interchangeable with a Git commit: the attestation also records commit, ref, repository, and dirty state when Git metadata is available, while the digest covers uncommitted and untracked meaningful source files too. Absolute workspace paths, mtimes, .git, .falsegreen, virtual environments, build outputs, and tool caches do not affect the digest; file contents, relative paths, entry types, normalized executable modes, and safe in-workspace symlink targets do.

Production attestations for accepted runs are Ed25519 signed. Call falsegreen_get_attestation_verification_key (or read falsegreen://attestation-key) for the raw base64 public key and stable key ID. Hosted reviewers can also fetch the same public material from GET /v1/attestation-key without an API key. The signature covers the canonical JSON document with signature.value set to null. Changing status, source binding, evidence, environment, or any other field invalidates it. Local deployments may leave signing optional; those artifacts say algorithm: "none" and the report explicitly says unsigned.

An attestation is evidence that the recorded criteria produced the recorded result for one exact source state. It is not a claim that a PR is universally safe, bug-free, or formally verified.

Commands

falsegreen mcp

Run the MCP server over STDIO. This is what Codex launches automatically. You rarely run this manually.

falsegreen login --token <key>

Activate this device and store credentials. Uses one of your device activation slots (2 by default, managed by Polar). The key is stored in ~/.config/falsegreen/credentials.toml.

falsegreen logout

Deactivate this device (frees the activation slot) and remove local credentials.

falsegreen status

Show authentication state, device activation ID, and API endpoint.

falsegreen install <agent>

Install FalseGreen into an agent's MCP configuration. Supported agents:

Each agent spawns falsegreen mcp as a local subprocess. The shim authenticates and communicates with the hosted service over HTTPS.

Configuration

Environment variables

Credentials file

~/.config/falsegreen/credentials.toml:

token = "POLAR_xxxxxxxxxxxxxxxx"
activation_id = "uuid-of-device-activation"

Why the shim is required for local workspaces

The hosted verifier cannot read paths on your machine. The shim snapshots the local workspace and uploads it before task creation, contract validation and freezing, and completion checks. Connecting directly to the HTTP MCP endpoint does not provide that filesystem bridge and therefore cannot verify a local workspace.

License

Apache-2.0. See LICENSE for details.