INTEGRATE

Claude Code

Use Phase from Claude Code in two ways.

Connections: Claude Code uses services such as AWS and PostgreSQL through your Agent Workflow's Connections, approved in the Phase Console. It only ever sees decoy credentials; the Phase AI proxy swaps in the live ones. See Phase AI.
Application secrets: Claude Code can list, create, rotate and delete secrets in your Phase apps without reading their values.

Prerequisites

The Phase CLI, installed and up to date.
Claude Code installed.
For Connections: an Agent and a Workflow in the Phase Console.

Setup

1. Log in

For Connections, log in with an Agent token for the Agent's Workflow, created in the Phase Console:

phase auth --mode token

For application secrets, log in as yourself with phase auth: Agent tokens can't access application secrets. To use Connections with your own login, set the Workflow in the next step with --workflow <workflowId>.

2. Enable Phase for Claude Code

Run this yourself, in your own terminal. Claude Code isn't allowed to run it.

phase ai enable --harness claude-code

It installs:

The phase-cli-ai-relay and phase-cli-app-secrets skills in ~/.claude/skills/.
The phase-ai-bootstrap hook plugin in ~/.claude/skills/phase-ai-bootstrap/, which starts the proxy and loads the Phase AI environment into Claude Code's shell.

It also creates the Phase AI CA and offers to trust it for your user (see The proxy CA), and asks whether Claude Code may read secret values.

3. Restart Claude Code

Fully quit and restart Claude Code (or Claude Desktop), start a new chat, then repeat your original prompt.

Using Connections

Every shell command Claude Code runs uses the Workflow's Connections while the Phase AI proxy runs. The hook starts the proxy when Claude Code needs it, and Claude Code's shell loads the Phase AI environment before each command, so provider CLIs and HTTP clients work with no wrapper. If the proxy isn't running, commands use your usual credentials.

Each session and prompt carries a Phase AI: status line, so Claude knows which Connections are ready. You can also launch Claude Code behind the proxy with phase ai run -- claude.

You: what can Phase manage here?
You: list the S3 buckets in our dev AWS account
You: count yesterday's orders in the analytics database

When the Workflow has no Connection for what you asked, Claude Code creates a request and shows you a link to it in the Phase Console. Create or choose the credential there and approve the request; Claude Code waits and then carries on. See Requests and approvals.

Managing application secrets

The phase-cli-app-secrets skill lets Claude Code work with your Phase apps and environments without seeing sensitive values:

List apps, environments and secret keys.
Create or rotate secrets with random values (--random), so the value never appears in the conversation.
Create and update non-sensitive config values.
Delete secrets, after confirming the app, environment and path.

You: list the secret keys in staging for the backend app
You: create STRIPE_WEBHOOK_SECRET as a sealed secret with a random value
You: rotate API_TOKEN in development
You: set LOG_LEVEL to debug in development

Claude Code doesn't read secret values (phase secrets get, phase secrets list --show, phase secrets export), import .env files, or run phase run or phase shell. Run those yourself in a terminal. When a sensitive value has to be entered by hand, Claude Code asks you to enter it in the Phase Console or your terminal rather than in the chat.

Secret visibility

Type	Visible to Claude Code	Description
`config`	Always	Non-sensitive configuration, such as ports, hosts and flags
`secret`	Your choice in `phase ai enable` (`--mask` or `--no-mask`)	Standard encrypted secrets
`sealed`	Never	Write-only secrets, such as API keys, tokens and passwords

Sealed secret values are never shown to AI agents, whatever you choose. Claude Code creates and rotates them with --random, so the value never appears in the conversation.

Security guardrails

Guardrail	Enforcement
Live provider credentials	Stay in the Phase AI proxy; Claude Code only sees decoys
Calls that mint new credentials (for example `sts:GetSessionToken`)	Blocked by the proxy
`phase ai enable` / `phase ai disable`	Blocked; run them yourself
`printenv`, `env`, `export`, `set`, `declare`, `compgen` inside `phase run`	Blocked by the CLI
`phase shell`	Blocked for AI agents
Sealed secret values in output	Always redacted
Secret values in `phase secrets` output	Redacted according to your visibility choice

Managing the integration

# Check setup, the proxy and the Workflow's Connections
phase ai status

# Refresh the skills and hook after a CLI upgrade
phase ai enable --harness claude-code

# Remove the integration
phase ai disable

# Print the Phase AI skill
phase ai skill

Troubleshooting

Claude Code doesn't know about Phase

Check that the skills are installed:

ls ~/.claude/skills/phase-cli-ai-relay/SKILL.md ~/.claude/skills/phase-cli-app-secrets/SKILL.md

If they're missing, run phase ai enable --harness claude-code and restart Claude Code.

Phase-managed commands fail

Run phase ai status and check the Proxy and Connections lines. A Connection must be ready. When Claude Code reports a Phase error, it quotes the X-Phase-Event-Id from the response, which you can look up in the Phase Console.

Authentication errors

Check who you're logged in as:

phase users whoami