aipaysdk
CLAUDE.md2 starsChanged 4 months agoMITView on GitHub
This is a monorepo for a macOS 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. 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…
- Installs packages
In this repository5 other files it gives its agents.
- skills/agentpay-sdk/agents/AGENTS.mdAGENTS.md
- skills/agentpay-sdk/agents/CLAUDE.mdCLAUDE.md
- skills/agentpay-sdk/agents/copilot-instructions.mdCopilot instructions
- add-pluginSkill
- agentpay-sdkSkill
The file
Files
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)
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
npm run test:ts
# Run a single TypeScript test
node --experimental-strip-types --test 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 @aipaysdk/relay test:unit
pnpm --filter @aipaysdk/web test:unit
# Relay deployment
pnpm --filter @aipaysdk/relay deploy:local
pnpm --filter @aipaysdk/relay deploy:development
pnpm --filter @aipaysdk/relay deploy:productionArchitecture
This is a monorepo for a macOS 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.
TypeScript CLI (src/cli.ts)
│ spawns Rust binaries
▼
Rust CLIs (vault-cli-*)
│ Unix socket / XPC
▼
Daemon (vault-daemon) ← Relay (apps/relay, tRPC/Hono) ← Web UI (apps/web, Next.js)Rust crates (crates/)
Organized in dependency layers:
- Domain (
vault-domain): Core types —AgentAction,SignRequest,SpendingPolicy,ManualApprovalRequest. No transport or IO dependencies. - Policy (
vault-policy): Policy evaluation engine consuming domain types. - Signer (
vault-signer): Signing backends — macOS Secure Enclave, software, TEE. Uses k256 for ECDSA. - Daemon (
vault-daemon): Authorization pipeline, encrypted state persistence (Argon2), nonce management. Transport-agnostic. - Transport (
vault-transport-unix,vault-transport-xpc): Wire protocols. Unix socket has 256KB max body. - SDK (
vault-sdk-agent): Agent-side client withAgentOperationstrait (approve(),transfer(),broadcast_tx()). - CLIs (
vault-cli-admin,vault-cli-agent,vault-cli-daemon): Binary entry points using clap.
TypeScript packages (packages/)
- config: Chain/network configuration, token profiles, RPC URLs
- rpc: Blockchain RPC via Viem — balance queries, tx broadcast, fee estimation
- ui: Shared React components (Tailwind CSS) for web app
- cache: Redis/Valkey client abstraction (ioredis)
Applications (apps/)
- relay: Hono + tRPC server, routes: daemon, admin, public. Backed by Valkey cache. Deploys via Serverless Framework.
- web: Next.js 16 + React 19. Approval console (
/approvals), daemon management (/daemons). Uses @noble crypto libs for client-side encryption.
CLI library (src/lib/)
66 TypeScript modules organizing CLI functionality: admin setup/reset, agent authentication (auth/rotate/revoke/migrate), asset broadcast, bootstrap, config management, macOS integration (launchd, keychain, Secure Enclave), wallet status/repair. The rust.ts module handles spawning Rust binaries.
Monorepo Tooling
- pnpm 10.6 workspaces (
packages/*,apps/*) - Turbo for task orchestration with caching (
turbo.json) - tsup bundles the CLI to
dist/cli.cjs(CJS, node20 target, with shebang) - Cargo workspace for Rust crates
- Biome for formatting/linting (line width 100, single quotes, 2-space indent, trailing commas)
- Rust 1.89.0+ minimum required
Testing
- TypeScript integration tests (
test/): Node.js built-intestmodule (not vitest). Tests use isolated home directories for CLI smoke tests. - Package/app unit tests: vitest (relay, web, cache).
- Rust tests: Standard
cargo test. Domain model, policy engine, and signer tests.
Key Conventions
- The CLI output is
dist/cli.cjs— a single CJS bundle despite the project being ESM ("type": "module") - Rust binaries install to
~/.agentpay/bin/ - macOS-specific: LaunchDaemon management, System Keychain storage, Secure Enclave signing
- Security-sensitive memory uses
zeroizein Rust - Web app enforces strict CSP and security headers
Instructions
- Always switch to Plan Mode whenever a complex task is being requested (3 or more steps in achieving it qualifies a task as being complex)
- Consistency is key, always write new code in the style of the already existing code, following the already availalble patterns
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

