Secret Handoff

Secret Handoff for Claude Code and Codex

Give your agent access with a sealed secret.

Let your agent use temporary passwords, tokens, and one-time codes without putting their values in the chat. The local tool opens a private browser page, shows why the agent needs access, and applies secrets to requests you approve. No vault to configure. No Secret Handoff account.

This repository publishes the Claude Code and Codex plugins for the signed Secret Handoff 0.0.4 release. It includes the skill, local stdio MCP configuration, Claude detection hooks, and a status-only Claude card. Secret entry stays in your browser. These are repository plugins, not claims of vendor-curated directory approval.

Install

Install CLI 0.0.4 first. Choose the archive for your platform and verify it with the release's SHA256SUMS. Run secrethandoff setup below to connect Claude Code and Codex when their CLIs are on PATH.

secrethandoff version

secrethandoff setup secrethandoff doctor

The expected version is 0.0.4. In the project where your agent works, run secrethandoff init to add credential guidance. Start a new agent session.

Claude Code

If you prefer to install the plugin yourself after installing the binary:

claude plugin marketplace add geland/secrethandoff-integrations

claude plugin install secrethandoff@secrethandoff

Codex

codex plugin marketplace add geland/secrethandoff-integrations

codex plugin add secrethandoff@secrethandoff

Restart the client or start a fresh session after installation. The binary must be on the PATH inherited by the client, including when launching a desktop app. secrethandoff doctor checks the local setup.

For a pinned marketplace, Codex accepts codex plugin marketplace add geland/secrethandoff-integrations --ref v0.0.4. Claude Code accepts the Git source https://github.com/geland/secrethandoff-integrations.git#v0.0.4 with claude plugin marketplace add. The release ZIP is also available for review.

Update an existing installation

Install the new binary first and verify that secrethandoff version reports 0.0.4. Both plugins launch the binary on your PATH.

Update Claude Code

claude plugin marketplace update secrethandoff

claude plugin update secrethandoff@secrethandoff

Update Codex

codex plugin marketplace upgrade secrethandoff

codex plugin add secrethandoff@secrethandoff

If your marketplace is pinned, switch its source to v0.0.4 first. Start a fresh agent session after updating. If you opted into Codex command approval, reapply the opt-in as described below.

Use

Ask your agent: “Use Secret Handoff for the temporary credential this task needs.” Enter the value only on the Secret Handoff browser page. Approve a narrow API host, method, and path. The agent uses a reference and receives redacted results. Ask the agent to forget the secret when the task is done.

Secrets live in the tool process's memory until forgotten or the process exits. Filled secrets do not have an automatic expiry timer. Approved APIs receive the value. run_with_secret requires browser command approval by default; an approved command receives the value and can leak it. Owners can opt into verified Claude Code native permission prompts or Codex approval settings; Codex settings may authorize automatically. These modes do not change how secrets are entered.

Claude detection hooks can block some accidental pastes before they reach the model. They cannot erase a value already saved in the client's local transcript. Never paste secrets into chat. Read the security boundaries.

Opt-in Codex command approval

With the supported binary and stable Codex 0.155.1 in the 0.155 series, or the exact desktop build 0.162.0-alpha.17.2, the owner can choose native host-policy authorization. It follows the owner's settings, including allow rules, hooks, and automatic review; a human click is not required in that mode. Browser approval remains the distribution default. Secret entry always stays on the isolated Secret Handoff page.

From a checkout of this repository, reload the plugin, run the owner opt-in helper, then start a fresh chat. The helper is not included in the review ZIP:

codex plugin add secrethandoff@secrethandoff

python3 scripts/configure_codex_approval.py codex \ --plugin-dir ~/.codex/plugins/cache/secrethandoff/secrethandoff/0.0.4

The helper validates and edits only the installed mcp.json and .mcp.json launch environment. It does not change host policies, reviewer, or hooks. Reinstallation resets the opt-in; rerun it after reload. Use browser instead of codex to restore browser command approval. Agents may apply it only when explicitly instructed by the owner.

python3 scripts/check_codex_approval.py tests live allow/deny delivery with a harmless server. python3 scripts/check_codex_approval.py --installed-plugin checks that the real cached plugin starts with native mode and can list a new empty store. Both use child-only isolation and no secrets. Pass --codex-bin /absolute/path/to/codex to either check to validate the desktop bundled executable instead of the terminal CLI. Run python3 -m unittest discover -s tests -p test_codex_approval_config.py for helper preservation and refusal tests. Desktop prompt rendering needs a separate owner-run dummy test. Command results report client_policy / host_policy, never a claim that a human clicked.

Grouped credentials

request_secrets asks for 2–8 credentials on one local browser page. A group name identifies the request; fields have separate names and optional labels. One policy applies to every field, and all values become ready together. Wait using the group name. Forgetting the group or any member erases all members. Phone/headless relay fill is currently unsupported for groups. Existing request_secret calls still collect one value. This feature does not change command approval settings.

Release scope

• Local handoffs for Claude Code and Codex, using secrethandoff mcp.
• Phone and remote relay handoffs are not enabled on the public service.
• One-time reveal links remain available separately at Share a secret.
• Other client configurations and listing drafts are retained for later testing; they are not published marketplace listings or verified host support claims.
• release-lock.json pins all six platform archives and six MCPB bundle hashes. Plugins start the binary on PATH; metadata does not replace or enforce that binary. Check secrethandoff version before use. Source and release provenance are available in the binary repository.

Development and validation

Use Python 3.11+ and Node 24. Install requirements-review.txt in a virtual environment, then run:

python scripts/test_release.py

python scripts/validate.py --release python scripts/package.py --release python scripts/test_package.py

tests/card.test.tsx runs with the Claude mod test runner. tests/card-state.test.mjs runs with Node and TypeScript available through SECRETHANDOFF_TEST_TYPESCRIPT. See 0.0.2 release status, agent evals, and contributor guidance.