# How do I verify Claude Code actions with Provely?

> Connect Claude Code to Provely through the MCP server, the CLI, the REST API. The guidance files, the hooks, and the CI gate.

Canonical: https://provely.sh/agents/claude-code  
Last reviewed: 2026-09-05  

**Claude Code connects to Provely through the MCP server, the CLI, the REST API. The agent does the action. Provely verifies the outcome and signs a receipt. Claude Code never holds the verifier credentials.**

A person verified the Claude Code capabilities on 2026-09-05. Agent products change monthly. Re-verify before you build.

Source: https://provely.sh/agents (retrieved 2026-09-05)

## Which surfaces does Claude Code use?

| Surface | Support | Detail |
| --- | --- | --- |
| [MCP server](/docs/mcp) | Supported | transport stdio, http; config `.mcp.json` |
| [CLI](/docs/cli) | Supported | Runs through the shell tool of the agent. |
| [SDK](/docs/sdk) | Not supported |  |
| [REST API](/docs/api) | Supported | Any HTTP call reaches the control plane. |

## Which guidance files does Claude Code read?

The renderer writes Agent Skills SKILL.md, CLAUDE.md fragment from one source. A new agent needs a profile, not core code.

| Format | Path | Mode |
| --- | --- | --- |
| Agent Skills SKILL.md | `.claude/skills/provely-outcome-verification/SKILL.md` | write |
| CLAUDE.md fragment | `CLAUDE.md` | append |
| Claude Code hook settings | `.provely/hooks/claude-settings.md` | fragment |
| CI gate workflow | `.provely/ci/github-actions.yml` | fragment |

## How is a false completion claim blocked?

| Enforcement | Support | Detail |
| --- | --- | --- |
| Advisory guidance | Supported | The instruction files state the rules for every agent. |
| Lifecycle hooks | Supported | `PostToolUse`, `Stop` |
| CI gate | Supported | `provely verify --wait` fails the pipeline unless the verdict is VERIFIED. |

## How do I connect Claude Code?

### Connect Claude Code to Provely

1. **Install the CLI.** Run `npx provely --version`, or download the static binary.
2. **Register the MCP server.** Add the Provely server to `.mcp.json`. Use `provely mcp` for stdio, or the hosted HTTP server with a bearer token. The tools are `begin`, `verify`, `status`, and `receipt`.
3. **Write the guidance files.** Run `provely init --agent claude-code`. It writes `.claude/skills/provely-outcome-verification/SKILL.md` (write), `CLAUDE.md` (append), `.provely/hooks/claude-settings.md` (fragment), `.provely/ci/github-actions.yml` (fragment). The guidance carries one rule: a successful tool call is not completion.
4. **Install the hooks.** Enable the `PostToolUse`, `Stop` hooks. A hook calls the CLI and blocks a completion claim while an operation is PENDING.
5. **Add the CI gate.** Run `provely verify --wait <duration>` in the pipeline. The step fails unless the verdict is VERIFIED. Exit codes: 0 VERIFIED, 2 PENDING, 3 FAILED, 4 CONTRADICTED, 5 UNVERIFIABLE.
6. **Report the verdict exactly as returned.** VERIFIED: "The action is verified complete. Receipt: <id>." PENDING: "The action is accepted but not yet verified. Operation: <id>."

## What else does the profile state?

- Verified 2026-09-05: hook events PostToolUse and Stop; exit 2 blocks a Stop and returns stderr to the agent; PostToolUse returns hookSpecificOutput.additionalContext. Source: https://code.claude.com/docs/en/hooks.
- Verified 2026-09-05: hooks live in .claude/settings.json, .claude/settings.local.json, or ~/.claude/settings.json. The Stop input carries stop_hook_active. Claude Code ends the turn after 8 consecutive blocks. Source: https://code.claude.com/docs/en/hooks.md.
- Verified 2026-09-05: skills live in .claude/skills/<name>/SKILL.md and MCP servers in .mcp.json. Source: https://code.claude.com/docs/en (skills, mcp).
- Register the two hook scripts with the snippet in .provely/hooks/claude-settings.md. The Stop hook calls `provely status --open --json`. While that flag does not exist (request I2), the hooks exit 0 and print a systemMessage that says enforcement is off.
- The hooks see only operations that called begin. An action that never opened an operation is invisible to them. The scanner and the CI gate cover that case.
- Headless runs (`claude -p`) use the CI gate in .provely/ci/github-actions.yml like every other pipeline.

> Claude Code keeps its action credentials, and no surface returns the verifier credentials to it. Read [the credential boundary](/docs/security). An operation outlives the session that opened it. Read [the API reference](/docs/api).

### Which host versions does the profile cover?

`>=2.0.0`. The integrations team last verified the profile with 2.1.261 on 2026-09-05 (npm @anthropic-ai/claude-code; CHANGELOG.md).

## Read next

- [Verify Codex actions](https://provely.sh/agents/codex)
- [Verify Cursor actions](https://provely.sh/agents/cursor)
- [Verify Resend actions](https://provely.sh/verify/resend)
- [See every agent integration](https://provely.sh/agents)
- [Read the MCP server reference](https://provely.sh/docs/mcp)
- [Read the credential boundary](https://provely.sh/docs/security)