falsegreen 0.1.1

# falsegreen

[![crates.io](https://img.shields.io/crates/v/falsegreen.svg)](https://crates.io/crates/falsegreen)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](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
- 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 (HTTP)
falsegreen install claude-code     # Claude Code (HTTP)
falsegreen install opencode        # OpenCode (HTTP)
falsegreen install cursor          # Cursor (HTTP)

# 3. Verify
codex mcp list   # for Codex
```

Codex will now launch `falsegreen mcp` as a STDIO MCP server. HTTP-based agents (Copilot, Claude Code, OpenCode, Cursor) connect directly to `mcp.falsegreen.com`.

| Tool | Purpose |
|------|---------|
| `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` | Run the independent verifier |
| `falsegreen_get_status` | Check task status without verifying |
| `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 |

## How it works

```
Coding agent (Codex, Claude Code, Cursor, ...)
  │
  │ STDIO MCP (JSON-RPC over stdin/stdout)
  ▼
falsegreen  ← this binary
  │
  │ 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
        │
        ├─ snapshot workspace source
        ├─ execute frozen acceptance criteria
        └─ return accepted / incomplete / unsafe
```

## 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:

| Agent | Command | Mode | Config file |
|-------|---------|------|-------------|
| Codex CLI & VS Code | `falsegreen install codex` | STDIO | `~/.codex/config.toml` |
| GitHub Copilot | `falsegreen install github-copilot` | HTTP | `.vscode/mcp.json` |
| Claude Code | `falsegreen install claude-code` | HTTP | `.mcp.json` |
| OpenCode | `falsegreen install opencode` | HTTP | `opencode.json` |
| Cursor | `falsegreen install cursor` | HTTP | `.cursor/mcp.json` |

STDIO agents spawn `falsegreen mcp` as a subprocess. HTTP agents connect directly to `mcp.falsegreen.com` with your `X-API-KEY` header.

## Configuration

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FALSEGREEN_KEY` | *(none)* | API key (overrides stored credentials) |
| `FALSEGREEN_API_URL` | `https://mcp.falsegreen.com/v1/mcp` | MCP service URL |

### Credentials file

`~/.config/falsegreen/credentials.toml`:

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

## Direct HTTP MCP (without the shim)

If your agent supports remote MCP servers, you can connect directly without installing the Rust binary:

```
URL: https://mcp.falsegreen.com/v1/mcp
Header: X-API-KEY: YOUR_FALSEGREEN_KEY
```

See the [documentation](https://falsegreen.com/docs) for agent-specific setup guides.

## License

Apache-2.0. See [LICENSE](LICENSE) for details.