use-agently: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Bun-based TypeScript monorepo for use-agently, a CLI tool for the Agently platform — a decentralized marketplace for AI agents using ERC-8004 and the x402 payment protocol. The CLI manages local EVM wallets, discovers agents, and communicates with them via the A2A (Agent-to-Agent) protocol.

Commands

# Install dependencies
bun install

# Build all packages (compiles to standalone binary via bun build --compile)
bun run build

# Run the CLI in development mode
bun run --filter use-agently dev

# Format code
bun run format

# Run tests
bun run test

All top-level commands use Turborepo (turbo) to orchestrate across packages.

Local Dev Test Loop

packages/localhost-aixyz is the local testing infrastructure for the CLI. It is a private aixyz agent that serves a free A2A endpoint at http://localhost:3000 so you can test use-agently a2a without hitting production agents or spending real funds.

# Terminal 1 — start the local agent (requires OPENAI_API_KEY in packages/localhost-aixyz/.env.local)
bun run --filter localhost-aixyz dev

# Terminal 2 — send a message via the CLI
use-agently a2a send --uri http://localhost:3000 -m "Hello!"

The agent exposes a free endpoint (accepts: { scheme: "free" }), so no wallet balance is needed. Set OPENAI_API_KEY in packages/localhost-aixyz/.env.local before starting the dev server.

Always use this agent when developing or testing changes to use-agently to maintain conformity and ensure every change is exercised end-to-end.

Architecture

• Monorepo: Bun workspaces with packages/* layout, Turborepo for task orchestration
• packages/localhost-aixyz: Local development agent (private, not published)
  • aixyz.config.ts — Agent metadata and skills
  • app/agent.ts — Free A2A endpoint (accepts: { scheme: "free" }) with echo tool
  • app/tools/echo.ts — Simple echo tool for testing
• packages/use-agently-sdk (@use-agently/sdk): The SDK package (published to npm)
  • client.ts — unstable_Client type, createClient(), fetch wrappers (dry-run, payment)
  • agently.ts — Agently platform API (search, getAgent for ERC-8004 resolution)
  • a2a.ts — A2A protocol: sendMessage, sendMessageStream, getAgentCard, URL resolution
  • mcp.ts — MCP protocol: listMcpTools, callMcpTool, URL resolution
  • wallets/ — Wallet interface and implementations (EVM private key)
  • utils/ — Chain config, transaction mode types
• packages/use-agently: The CLI package
  • src/bin.ts — Executable entry point (#!/usr/bin/env bun)
  • src/cli.ts — Commander.js program setup, registers all commands
  • src/config.ts — Config persistence at ~/.use-agently/config.json (load, save, backup)
  • src/client.ts — Creates defaultClient via createClient() with CLI user-agent; all CLI commands use this client
  • src/commands/ — One file per CLI command (init, whoami, balance, search, a2a)
  • Build output: build/use-agently (standalone binary via bun build --compile)