# Invariance

> Invariance is observability and verification for AI agents. Every agent run becomes a typed, cited, verifiable graph of nodes — Eyes writes it, Cortex reads it, DNA is it. CLI, MCP server, and TypeScript/Python SDKs all expose the same surface so agents can inspect their own behavior.

Every read command and SDK method supports JSON output, structured errors with stable `code` values, and stable IDs. Coding agents — Claude Code, Codex, Cursor, customer agents — are first-class consumers.

## Onboarding

A human partner provisions the API key (dashboard → Settings → API keys → "New API key"). Once `INVARIANCE_API_KEY` is set, agents self-operate.

- [Quick Start](https://useinvariance.com/docs/quickstart): five-minute path from key to first traced run.
- [Authentication](https://useinvariance.com/docs/auth): key formats, header usage, tiers.

## Docs

- [Overview](https://useinvariance.com/docs)
- [Concepts](https://useinvariance.com/docs/concepts): runs, nodes, sessions, findings, proof chain.
- [CLI](https://useinvariance.com/docs/cli): full `inv` command reference.
- [Configuration](https://useinvariance.com/docs/configuration): env vars, SDK init, provider targets.
- [Modules](https://useinvariance.com/docs): SDK module reference (init, sessions, recording, agents, policy, identity, observability, queries, evals, monitors).

## Raw markdown for agents

Any docs page is fetchable as plain markdown via the `/raw/docs/...` prefix:

- `curl https://useinvariance.com/raw/docs/quickstart`
- `curl https://useinvariance.com/llms-full.txt` — single-file concatenation of every docs page.

## Agent skill files

One-liner to install a platform-specific skill file into the current repo:

```
curl -fsSL https://useinvariance.com/install-agent-skill.sh | sh
```

Supported: Claude Code, Codex, Cursor, Windsurf, Cline, Aider, Continue, generic AGENTS.md.

## Surface map

- CLI (`@invariance/cli`): `inv` binary. Global `--json`. Exit codes: `0` ok, `1` error, `2` `API_NOT_AVAILABLE`. Error codes: `AUTH_ERROR`, `NOT_FOUND`, `API_ERROR`, `CONFIG_ERROR`, `NETWORK_ERROR`, `API_NOT_AVAILABLE`, `UNEXPECTED_ERROR`.
- MCP (`@invariance/mcp`): stdio + HTTP. Tools named `invariance_<resource>_<action>`. All annotated `readOnlyHint` / `destructiveHint`.
- TypeScript SDK (`@invariance/sdk`): typed, `.d.ts` shipped.
- Python SDK (`invariance-sdk`): PEP 561 typed, sync + async.

## Conventions

- Auth: `INVARIANCE_API_KEY` env var, or `~/.invariance/config.json`.
- In `--json` mode, stdout is a single parseable JSON document; warnings/progress go to stderr.
- Errors in `--json` mode: `{"error":{"code","message","status_code"?}}` on stderr.
- MCP tool outputs mirror corresponding CLI JSON shape where practical.