agentpay-sdk: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

# Install dependencies (also builds Rust binaries via postinstall when cargo is on PATH;
# without cargo, postinstall warns and exits 0 unless AGENTPAY_REQUIRE_RUST_INSTALL=1)
pnpm install

# Build everything (Turbo + tsup CLI bundle)
npm run build

# Full check (cargo test compile + turbo typecheck)
npm run check

# TypeScript type checking
npm run typecheck

# Lint (Biome)
npm run lint
npm run lint:fix          # auto-fix

# Run all TypeScript integration tests (isolated HOME/AGENTPAY_HOME/TMPDIR sandbox under the
# system temp dir; sudo, launchctl, and systemctl are stubbed out)
npm run test:ts

# Run a single TypeScript test through the same isolated harness (tsx, not --experimental-strip-types)
node scripts/run-ts-tests.mjs test/<file>.test.mjs

# Run Rust tests
cargo test --workspace

# Run a single Rust crate's tests
cargo test -p vault-domain

# Build/install Rust binaries to ~/.agentpay/bin
npm run install:rust-binaries

# Package-specific commands (vitest)
pnpm --filter @worldlibertyfinancial/agent-relay test:unit
pnpm --filter @worldlibertyfinancial/agent-web test:unit

# Relay deployment: these scripts are fail-closed stubs (scripts/unsupported-release-surface.mjs)
# that print "unsupported in this release" and exit 1. Relay deployment is not supported.
pnpm --filter @worldlibertyfinancial/agent-relay deploy:local
pnpm --filter @worldlibertyfinancial/agent-relay deploy:development
pnpm --filter @worldlibertyfinancial/agent-relay deploy:production

Architecture

This is a monorepo for a macOS/Linux signing CLI built around a self-custodial local daemon. The system has two language layers: Rust handles cryptography, policy evaluation, and daemon operations; TypeScript handles CLI orchestration, configuration, and web interfaces.

How the layers interact (daemon mode)

The TypeScript CLI (src/cli.ts) is the user-facing entry point (agentpay). It spawns Rust binaries (vault-cli-admin, vault-cli-agent, vault-cli-daemon) as child processes for security-critical operations. The Rust daemon runs persistently and communicates via Unix domain sockets (or macOS XPC). The relay server bridges external requests to the daemon, and the web UI provides a manual approval console.