agent-integration.md

Agent Integration

Locksmith gives AI agents secure access to secrets with per-session caching. This document describes the integration protocol for all supported agent platforms.

Protocol

Every agent that may need secrets follows three steps:

Step 1 - Check for an existing session

Before doing any work, check whether LOCKSMITH_SESSION is already set in the environment. If it is, use it - no action needed.

Step 2 - Ensure a session exists

If LOCKSMITH_SESSION is not set (or is empty), run:

export LOCKSMITH_SESSION=$(locksmith session ensure --quiet)

locksmith session ensure reuses an existing valid session from the environment or creates a new one. It exits non-zero if the daemon is not running - handle this gracefully (secrets will be unavailable, but work should continue).

Step 3 - Retrieve secrets

Use --key when the alias is configured in ~/.config/locksmith/config.yaml:

locksmith get --key openai_api_key
locksmith get --key github_token

Use --path + --vault to access a secret directly by its path in the vault (no alias needed):

locksmith get --vault gopass --path work/aws/access-key-id
locksmith get --vault keychain --path "My API Token"

The session is reused automatically for subsequent calls within the same session TTL (default: 3h).

Sub-agent Delegation

When spawning sub-agents, pass LOCKSMITH_SESSION in their environment:

# Sub-agent reuses the parent session - no re-authorization needed.
LOCKSMITH_SESSION=$LOCKSMITH_SESSION some-agent-tool ...

This behavior is controlled by agent.pass_session_to_subagents in ~/.config/locksmith/config.yaml (default: true). When set to false, each sub-agent must obtain its own session independently.

Platform Support

Platform	Session automation	Sub-agent passing	Notes
Claude Code	UserPromptSubmit hook injects env (auto-installed by locksmith init)	Via instructions	Restart Claude Code after init
Codex	SessionStart hook pre-warms daemon (auto-installed by locksmith init); env still via instructions	Via instructions	Codex prompts the user to trust the hook on next run
Gemini CLI	Via instructions in GEMINI.md (no hook)	Via instructions
OpenCode	Via instructions in instructions.md (no hook)	Via instructions

Other agents (Cursor, Copilot CLI, etc.) are not auto-detected by locksmith init; they fall through to the generic installer which writes a standalone ~/.config/locksmith/agent-instructions.md.

Claude Code Hook Setup

Run locksmith init - the hook is installed automatically when Claude Code is detected. init performs five actions:

1. Registers a UserPromptSubmit hook in ~/.claude/settings.json that invokes locksmith session ensure --hook. The command emits the JSON env block via encoding/json; there is no shell script intermediary.
2. Adds Bash(locksmith:*) to permissions.allow so any direct locksmith invocation the agent makes through the Bash tool runs without an extra approval dialog. The hook itself runs through Claude Code's hook subsystem, not Bash, so it does not need a separate permission entry.
3. Appends a PATH-augmentation block to the user's shell rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish) when the locksmith binary directory is not already in $PATH. The snippet is idempotent at shell-startup time and locksmith never creates a shell rc file that does not already exist.
4. Migrates any pre-existing reference to the deprecated ~/.config/locksmith/agent-hook.sh script: the command value in settings.json is rewritten to the native invocation, the matching Bash(.../agent-hook.sh) permission rule is removed, and the on-disk script is deleted.
5. Restarts any currently-running locksmith daemon so newly installed plugins and config changes take effect immediately. If no daemon is running, the next agent prompt or shell startup will spawn one.

All five actions are idempotent: re-running init will not duplicate entries. After init, restart any running AI agent so it picks up the updated instructions.

Manual setup

If you prefer to install the hook without using init, add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "locksmith session ensure --hook"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": ["Bash(locksmith:*)"]
  }
}

Ensure the directory containing locksmith is on PATH for non-login shells. On most systems adding the following to your ~/.zshrc or ~/.bashrc is sufficient:

case ":$PATH:" in
  *":/your/locksmith/dir:"*) ;;
  *) export PATH="$PATH:/your/locksmith/dir" ;;
esac

The hook exits silently if the locksmith daemon is not running, so it never blocks agent work.

Codex Hook Setup

Run locksmith init - when Codex is detected, a SessionStart hook is added to ~/.codex/hooks.json that pre-warms the locksmith daemon session so vault unlock (passphrase, biometric) fires before the agent's first secret request.

Unlike the Claude Code hook, the Codex hook does not inject environment variables. Codex hooks cannot deliver env vars to the agent shell, so users still run

export LOCKSMITH_SESSION=$(locksmith session ensure --quiet)

in their shell session (or rely on locksmith get auto-starting a session). The Codex SessionStart hook only removes the latency spike on the first vault touch.

The hook installed by locksmith init is best-effort: stdout and stderr are redirected to /dev/null and the command trails || true so it never blocks Codex startup. The install is idempotent: running init again does not duplicate the entry, and third-party SessionStart hooks already present in hooks.json are preserved.

Codex prompts the user to trust new hooks on the next session start (/hooks command). Locksmith does not auto-trust the hook on the user's behalf.

Manual setup

If you prefer to install the hook without using init, add to ~/.codex/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "locksmith session ensure --quiet >/dev/null 2>&1 || true",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Locksmith Config Reference

agent:
  pass_session_to_subagents: true   # default: true

See Configuration Reference for the full reference.