solana-agent-kit: 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 (requires pnpm 9+, Node 22+)
pnpm install

# Build all packages
pnpm run build

# Build specific packages
pnpm run build:core              # Core package only
pnpm run build:plugin-token      # Token plugin
pnpm run build:plugin-defi       # DeFi plugin
pnpm run build:plugin-nft        # NFT plugin
pnpm run build:plugin-misc       # Misc plugin
pnpm run build:plugin-blinks     # Blinks plugin
pnpm run build:adapter-mcp       # MCP adapter

# Lint and format
pnpm run lint                    # Check with Biome
pnpm run lint:fix                # Auto-fix lint issues
pnpm run format                  # Format code with Biome

# Run tests (interactive - prompts for "agent" or "programmatic" mode)
# Requires OPENAI_API_KEY, RPC_URL, SOLANA_PRIVATE_KEY in test/.env
pnpm run test

# Generate documentation
pnpm run docs

# Clean all build artifacts
pnpm run clean

Architecture Overview

This is a monorepo using pnpm workspaces and Turborepo for building AI agents that interact with Solana protocols.

Package Structure

packages/
├── core/           # solana-agent-kit - Main SDK with SolanaAgentKit class
├── plugin-token/   # Token operations (transfers, swaps, Jupiter, PumpFun)
├── plugin-defi/    # DeFi protocols (Drift, Orca, Raydium, Meteora, etc.)
├── plugin-nft/     # NFT operations (Metaplex, 3Land)
├── plugin-misc/    # Utilities (CoinGecko, Allora, domains, webhooks)
├── plugin-blinks/  # Solana Blinks (arcade games)
└── adapter-mcp/    # Model Context Protocol server adapter

Core Concepts

Plugin System: V2 uses a composable plugin architecture. Plugins register methods (direct function calls) and actions (AI agent tools with schemas).

// Plugin structure
interface Plugin {
  name: string;
  methods: Record<string, Function>;  // Programmatic API
  actions: Action[];                   // AI agent tools with Zod schemas
  initialize(agent: SolanaAgentKit): void;
}

// Action structure for AI tools
interface Action {
  name: string;
  similes: string[];           // Alternative trigger phrases
  description: string;
  examples: ActionExample[][];
  schema: z.ZodType<any>;      // Input validation
  handler: Handler;            // Execution function
}