# falsegreen
[](https://crates.io/crates/falsegreen)
[](LICENSE)
**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
```sh
cargo install falsegreen
```
## Quick start
```sh
# 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.
| `falsegreen_create_task` | Register a new task with a goal |
| `falsegreen_save_contract_draft` | Draft acceptance criteria |
| `falsegreen_validate_contract` | Validate the contract draft |
| `falsegreen_freeze_contract` | Freeze the contract (locks criteria + verifier) |
| `falsegreen_get_assignment` | Get compact immutable requirements |
| `falsegreen_check_completion` | Start the independent verifier; hosted runs return a polling state |
| `falsegreen_get_status` | Poll task status without verifying or uploading the workspace |
| `falsegreen_get_verification_artifacts` | Get source-bound JSON attestation and PR report |
| `falsegreen_get_attestation_verification_key` | Get the public Ed25519 verification key |
| `falsegreen_get_repair_feedback` | Get failure details from the last run |
| `falsegreen_get_contract_schema` | Get the JSON schema for contracts |
| `falsegreen_get_contract` | Get the frozen contract |
| `falsegreen_mark_unresolved` | Mark a task as unresolved |
| `falsegreen_close_task` | Close a stale non-accepted task without claiming acceptance |
| `falsegreen_list_tasks` | List task lifecycle state and cleanup eligibility |
## 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; the compact values are also shown in the Markdown report.
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:
| Codex CLI & VS Code | `falsegreen install codex` | STDIO | `~/.codex/config.toml` |
| GitHub Copilot | `falsegreen install github-copilot` | STDIO | `.vscode/mcp.json` |
| Claude Code | `falsegreen install claude-code` | STDIO | `.mcp.json` |
| OpenCode | `falsegreen install opencode` | STDIO | `opencode.json` |
| Cursor | `falsegreen install cursor` | STDIO | `.cursor/mcp.json` |
Each agent spawns `falsegreen mcp` as a local subprocess. The shim authenticates
and communicates with the hosted service over HTTPS.
## Configuration
### Environment variables
| `FALSEGREEN_KEY` | *(none)* | API key (overrides stored credentials) |
| `FALSEGREEN_API_URL` | `https://mcp.falsegreen.com/v1/mcp` | MCP service URL |
| `FALSEGREEN_WORKSPACE_URL` | derived from MCP URL | Workspace upload URL (self-hosted overrides only) |
### Credentials file
`~/.config/falsegreen/credentials.toml`:
```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](LICENSE) for details.