Quickstart

Get from zero to your first signed verdict in about five minutes.

Prerequisites

• Claude Code installed and authenticated
• Git configured (git config user.name + user.email)
• A repo you don’t mind Thoth-ATO writing files into. A fresh empty directory works.

1. Install

Install the Claude Code plugin and run governed cycles entirely in your editor on Claude, at no cost. Add the marketplace, then install the plugin:

claude plugin marketplace add integratedvs/Thoth-ATO
claude plugin install thoth-ato

Claude Code fetches the manifest from the Thoth-ATO marketplace, registers the /thoth and /thoth-config slash commands, and installs the bundled skills. No reload needed.

Image TBD — plugin install confirmation screen.

The local loop runs on Claude. Free local cycles are unlimited.

Run the full cycle on any provider

Want to run the full governed cycle on the provider of your choice — Anthropic, OpenAI, Gemini, Vertex, Ollama, LM Studio, or a custom OpenAI-compatible endpoint? Dispatch a remote cycle to the Thoth-ATO hosted control plane, straight from the plugin:

/thoth --remote "Build a CLI that converts CSV to JSON, with tests."

A remote cycle runs the full cycle on your chosen provider via the hosted control plane. Same governance, same signed verdicts. A standalone thoth CLI for any terminal and CI is in pre-launch beta — installable from source today; it is published to npm at the v7.2 launch gate.

Model providers

The full governed cycle runs on any supported provider — Anthropic, OpenAI, Gemini, Vertex, Ollama, LM Studio, or a custom OpenAI-compatible endpoint — via a remote cycle (/thoth --remote) on the hosted control plane. Select a provider with /thoth-config set-provider, or wire it through THOTH_LLM_PROVIDER / THOTH_LLM_MODEL; see the CLI reference.

The local Claude Code plugin runs the loop on Claude. Its --provider override only changes the Judge and subagents, not the loop itself. Full local multi-provider support is on the roadmap.

Note

The standalone thoth CLI for any terminal and CI — including the integrated terminal of your IDE — is in pre-launch beta: installable from source today, published to npm at the v7.2 launch gate. Native IDE extensions are on the roadmap.

2. Configure your API key (optional)

Local cycles run entirely in your editor and require no API key. Skip this step unless you plan to use /thoth --remote or want to bind your local install to your Thoth-ATO account for usage analytics.

/thoth-config set-api-key thk_...

The key is written to your OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). It is never written to plaintext config files. It is never sent anywhere except api.thothato.io over TLS 1.3 with certificate pinning.

Get a key from https://thothato.io/dashboard/api-keys.

Common error: missing API key

Error: remote dispatch requires an API key.
Run `/thoth-config set-api-key thk_...` first, or omit `--remote` to run locally.
Exit code: 10

This means you tried /thoth --remote without configuring a key. Fix by storing one, or drop --remote.

3. Run your first cycle

In any repo, open Claude Code and run:

/thoth Build a CLI that converts CSV to JSON, with tests.

Image TBD — phase tracker with Specify → Plan → Execute → Verdict.

What happens, phase by phase:

1. Specify — Thoth-ATO decomposes your goal into Root Intent → Component Intents → Task Intents. You see the decomposition and can revise it.
2. Plan — The Lead worker proposes a DAG of tasks with explicit dependencies. You approve, edit, or reject.
3. Execute — Workers invoke Write, Edit, Bash directly in Claude Code. Files appear on disk. Tests run. Failures trigger a bounded self-healing loop (default 3 iterations).
4. Verdict — The Judge scores the deliverable on 6 principles (Security, Cost, Performance, Scalability, Anti-fragility, Extensibility) and emits a cryptographically signed verdict.

Total wall time for the example goal: usually 90–180 seconds.

Common notice: signed-verdict quota reached

Notice: signed-verdict quota reached for current billing period (50/50 used).
This cycle completed and its deliverable is returned, marked unsigned_quota_exceeded.
Upgrade at https://thothato.io/pricing for unlimited signed verdicts.
Exit code: 11

The cycle still completes and returns its deliverable; only the verdict signature is withheld, and the deliverable is marked unsigned_quota_exceeded. Free-tier accounts get 50 signed verdicts per month; local cycles and unsigned remote cycles are unlimited. Upgrade to Pro for unlimited signed verdicts.

4. Inspect the verdict

The verdict file is written to .thoth/verdicts/<cycle-id>.json. Open it. You’ll see:

{
  "cycleId": "cyc_01HXXXX",
  "kmsKeyVersion": "projects/p/locations/l/keyRings/r/cryptoKeys/judge/cryptoKeyVersions/1",
  "principles": {
    "security": 0.92,
    "cost": 0.88,
    "performance": 0.95,
    "scalability": 0.90,
    "antiFragility": 0.87,
    "extensibility": 0.91
  },
  "constitutionRef": "sha256:abc...",
  "deliverableHash": "sha256:def...",
  "issuedAt": "2026-05-16T12:04:30Z",
  "verdictHash": "BASE64_ED25519_SIGNATURE"
}

To verify the signature cryptographically, see Verdict verification.

To inspect the worker tool calls and prompts that produced the deliverable, look at .thoth/cycles/<cycle-id>/transcript.jsonl.

5. Next steps

CLI reference All commands, flags, exit codes, and environment variables.

API reference Drive cycles from CI/CD via REST.

Verdict verification Verify any verdict in Node, Python, Go, or Rust.

Compliance Map verdicts to EU AI Act and SOC2 controls.

What’s next?

If you got a verdict written, you have a working install. Read the CLI reference next for the full command surface, or jump to Verdict verification to learn how to verify the signature you just received.