{"id":23468929,"url":"https://github.com/ian/hybrid","last_synced_at":"2026-02-04T18:02:20.222Z","repository":{"id":142757400,"uuid":"614072212","full_name":"ian/hybrid","owner":"ian","description":"Hybrid - Typescript framework for building crypto AI agents.","archived":false,"fork":false,"pushed_at":"2025-11-17T18:44:04.000Z","size":2621,"stargazers_count":16,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T23:42:47.450Z","etag":null,"topics":["agents","coinbase","react","xmtp"],"latest_commit_sha":null,"homepage":"https://hybrid.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-14T20:45:52.000Z","updated_at":"2025-12-07T19:11:14.000Z","dependencies_parsed_at":"2025-09-08T00:13:29.073Z","dependency_job_id":"2ba1153b-fad3-4409-9814-8991ecb33720","html_url":"https://github.com/ian/hybrid","commit_stats":null,"previous_names":["hybridhq/hybrid"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/ian/hybrid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ian%2Fhybrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ian%2Fhybrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ian%2Fhybrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ian%2Fhybrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ian","download_url":"https://codeload.github.com/ian/hybrid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ian%2Fhybrid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29092714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","coinbase","react","xmtp"],"created_at":"2024-12-24T14:37:24.374Z","updated_at":"2026-02-04T18:02:20.217Z","avatar_url":"https://github.com/ian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hybrid - Typescript Framework for building crypto AI Agents.\n\nAn open-source agent framework for building conversational AI agents on XMTP. \n\nHybrid makes it easy for developers to create intelligent agents that can understand natural language, process messages, and respond through XMTP's decentralized messaging protocol.\n\nSee [hybrid.dev](https://hybrid.dev) for more information.\n\n## 📦 Quickstart\n\nGetting started with Hybrid is simple:\n\n### 1. Initialize your project\n\n```bash\nnpm create hybrid my-agent\ncd my-agent\n```\n\nThis creates all the necessary files and configuration for your agent.\n\n### 2. Get your OpenRouter API key\n   \nVisit [OpenRouter](https://openrouter.ai/keys), create an account and generate an API key\n\nAdd it to your `.env` file:\n\n```env\nOPENROUTER_API_KEY=your_openrouter_api_key_here\n```\n\n### 3. Generate XMTP keys\n\n```bash\nhybrid keys\n```\n\nor automatically add it to your `.env` file:  \n\n```bash\nhybrid keys --write\n```\n\n### 4. Register your wallet with XMTP\n\n```bash\nhybrid register\n```\n\nThis generates secure wallet and encryption keys for your XMTP agent.\n\n  ### 5. Start developing\n\n```bash\nhybrid dev\n```\n\nYour agent will start listening for XMTP messages and you're ready to build! \n\nGo to [https://xmtp.chat/dm/](https://xmtp.chat/dm/) and send a message to your agent.\n\n## 🧠 Agent Behaviors\n\n`hybrid` comes with a set of behaviors that you can use to customize your agent's behavior. Behaviors are executed before or after the agent responds.\n\n### Basic Agent\n\nHere's a basic agent implementation:\n\n```typescript\nimport { createOpenRouter } from \"@openrouter/ai-sdk-provider\"\nimport { Agent } from \"hybrid\"\nimport { filterMessages, reactWith, threadedReply } from \"hybrid/behaviors\"\n\nexport const openrouter = createOpenRouter({\n\tapiKey: process.env.OPENROUTER_API_KEY\n})\n\nconst agent = new Agent({\n\tname: \"Basic Agent\",\n\tmodel: openrouter(\"x-ai/grok-4\"),\n\tinstructions:\n\t\t\"You are a XMTP agent that responds to messages and reactions. Be conversational.\"\n})\n\nawait agent.listen({\n\tport: process.env.PORT || \"8454\"\n})\n```\n\n### Message Filtering\n\nBy default, the agent will process all messages in the conversation. You can filter messages by using the `filterMessages` behavior.\n\n```typescript\nimport { filterMessages } from \"hybrid/behaviors\"\n\nawait agent.listen({\n\tport: process.env.PORT || \"8454\",\n\tbehaviors: [\n      filterMessages((filter) =\u003e\n        filters.isReply() || filters.isDM() || filters.hasMention(\"@agent\")\n      )\n    ]\n})\n```\n\nThe filter function receives a `filter` object with methods that return boolean values. Return `true` to process the message, `false` to filter it out.\n\n**Available filter methods:**\n- `filter.isText()` - Message is text content\n- `filter.isReply()` - Message is a reply\n- `filter.isReaction()` - Message is a reaction\n- `filter.isReaction(emoji, action?)` - Message is a reaction with specific emoji and/or action (\"added\" | \"removed\")\n- `filter.isDM()` - Message is a direct message\n- `filter.isFromSelf()` - Message is from the agent itself\n- `filter.isFromSelf()` - Message is from the agent itself (alias for isFromSelf)\n- `filter.isFrom(address)` - Message is from a specific Ethereum address (async)\n- `filter.hasMention(mention:string)` - Message contains a mention\n- `filter.hasContent()` - Message has content\n- `filter.isGroup()` - Message is in a group conversation\n- `filter.isGroupAdmin()` - Message sender is group admin\n- `filter.isGroupSuperAdmin()` - Message sender is group super admin\n- `filter.isRemoteAttachment()` - Message has remote attachment\n- `filter.isTextReply()` - Message is a text reply\n\n**Using async filters:**\n\nFilters can now be async to support operations like address resolution:\n\n```typescript\nfilterMessages(async (filter) =\u003e \n  !await filter.isFrom(\"0x1234567890123456789012345678901234567890\") \u0026\u0026 \n  !filter.isFromSelf()\n)\n```\n\nSee XMTP Agent SDK filter docs for all filtering options: [XMTP Agent SDK – Built-in filters](https://github.com/xmtp/xmtp-js/tree/main/sdks/agent-sdk#3-builtin-filters).\n\n### Reactions\n\nA common behavior for agents is to react to the inbound message to let others know the agent is aware of the message and will reply.\n\n```typescript\nimport { reactWith } from \"hybrid/behaviors\"\n\nawait agent.listen({\n\tport: process.env.PORT || \"8454\",\n\tbehaviors: [reactWith(\"👀\")]\n})\n```\n\n### Threaded Replies\n\nBy default, the agent will reply to the dm / group message in a top-level manner. You can change this to a threaded manner by using the `threadedReply` behavior. This will have the agent reply to the original message and start a thread.\n\n```typescript\nimport { threadedReply } from \"hybrid/behaviors\"\n\nawait agent.listen({\n\tport: process.env.PORT || \"8454\",\n\tbehaviors: [threadedReply()]\n})\n```\n\n## 🛠️ Tools Standard Library\n\nHybrid includes a comprehensive standard library of tools for building crypto-enabled agents:\n\n### Blockchain Tools (`blockchainTools`)\n\n```typescript\nimport { Agent } from \"hybrid\"\nimport { blockchainTools } from \"hybrid/tools\"\n\nconst agent = new Agent({\n  name: \"my-agent\",\n  model: myModel,\n  tools: blockchainTools,\n  // Expose runtime configuration used by blockchain tools\n  createRuntime: () =\u003e ({\n    rpcUrl: process.env.RPC_URL,\n    privateKey: process.env.PRIVATE_KEY as `0x${string}` | undefined,\n    defaultChain: \"mainnet\" as const\n  }),\n  instructions: \"You can check balances, send transactions, and interact with the blockchain.\"\n})\n```\n\n**Available Tools:**\n- `getBalance` - Get native token balance for any address\n- `sendTransaction` - Send native tokens to another address\n- `getTransaction` - Get transaction details by hash\n- `getBlock` - Get blockchain block information\n- `getGasPrice` - Get current gas prices\n- `estimateGas` - Estimate gas costs for transactions\n\n**Supported Chains:** Ethereum, Polygon, Arbitrum, Optimism, Base, and Sepolia testnet\n\n### XMTP Tools\n\nThe XMTP plugin automatically includes the following tools when your agent starts listening for messages:\n\n**Available Tools:**\n- `sendMessage` - Send messages to XMTP conversations\n- `sendReply` - Reply to specific messages\n- `sendReaction` - Send emoji reactions\n- `getMessage` - Retrieve message details by ID\n\nThese tools are automatically available to your agent without needing to explicitly include them in your agent configuration.\n\n### Using Blockchain Tools\n\n```typescript\nimport { Agent } from \"hybrid\"\nimport { blockchainTools } from \"hybrid/tools\"\n\nconst agent = new Agent({\n  name: \"blockchain-agent\",\n  model: myModel,\n  tools: blockchainTools,\n  createRuntime: () =\u003e ({\n    rpcUrl: process.env.RPC_URL,\n    privateKey: process.env.PRIVATE_KEY as `0x${string}` | undefined,\n    defaultChain: \"mainnet\" as const\n  })\n})\n```\n\n## 🖥️ CLI Commands\n\nThe Hybrid CLI provides several commands to manage your agent development workflow:\n\n```bash\n# Initialize a new agent project\nnpm create hybrid\n\n# Use the CLI\nhybrid keys\nhybrid dev\nhybrid build\nhybrid clean\nhybrid upgrade\nhybrid register\nhybrid revoke \u003cinboxId\u003e\nhybrid revoke:all\n\n# Or use project scripts generated by create-hybrid\npnpm dev\npnpm build\npnpm start\n```\n\n## 🔧 Developing Locally\n\nIf you want to work with the source code or contribute to Hybrid:\n\n### Prerequisites\n\n- **Node.js**: Version 22 or higher\n- **pnpm**: Package manager\n- **Git**: Version control\n\n### 1. Clone and Install\n\n```bash\ngit clone \u003crepository-url\u003e\ncd hybrid\npnpm install\n```\n\n### 2. Environment Setup\n\nCreate a `.env.local` file in the root directory:\n\n```env\n# AI Configuration\nOPENROUTER_API_KEY=\"your_openai_api_key\"\n\n# XMTP Configuration\nXMTP_WALLET_KEY=\"0x...\"  # Private key for XMTP agent\nXMTP_DB_ENCRYPTION_KEY=\"...\"  # Database encryption key\nXMTP_ENV=\"dev\"  # dev, production\n```\n\n### 3. Start Development Server\n\n```bash\n# Start the agent\npnpm dev\n```\n\nThis starts the agent and begins listening for XMTP messages on the configured port (default: 8454).\n\n## 🛠️ Development\n\n### Available Scripts\n\n```bash\n# Development\npnpm build                  # Build all packages\npnpm build:watch            # Build all packages in watch mode\npnpm test                   # Run tests across all packages\npnpm typecheck              # Type checking across all packages\n\n# Code Quality\npnpm lint                   # Lint all packages\npnpm lint:fix               # Fix linting issues\npnpm format                 # Format code (handled by Biome)\n\n# Maintenance\npnpm clean                  # Clean build artifacts\npnpm nuke                   # Remove all node_modules (nuclear option)\npnpm bump                   # Bump version (patch by default)\npnpm bump:patch             # Bump patch version\npnpm bump:minor             # Bump minor version\npnpm bump:major             # Bump major version\n\n# Release\npnpm release                # Build and publish all packages\n```\n\n### Project Structure\n\nHybrid is designed as a framework for developers to build XMTP agents:\n\n#### Basic Example (`examples/basic`)\n- **Message Processing**: Handle incoming XMTP messages with custom filters\n- **AI Integration**: Connect any AI model for natural language understanding\n- **Agent Configuration**: Simple setup with instructions and behavior\n- **XMTP Listening**: Built-in server to listen for messages on any port\n\n#### Core Packages\n- **core/**: Main agent framework library (published as \"hybrid\")\n  - Agent runtime and plugin system\n  - Type-safe message handling\n  - Flexible filtering and processing\n  - Integration with AI providers and XMTP\n- **cli/**: Command-line interface for agent management\n  - Project initialization and setup\n  - XMTP key generation and management\n  - Development server and build tools\n- **utils/**: Common utilities and helpers (@hybrd/utils)\n  - Array, string, and object utilities\n  - Date and UUID helpers\n  - Markdown processing utilities\n- **xmtp/**: XMTP client and messaging utilities (@hybrd/xmtp)\n  - Client initialization and management\n  - Message sending and receiving\n  - Address resolution (ENS, BaseName, XMTP)\n  - Content type handling and encryption\n\n### Key Technologies\n\n- **Core**: Node.js 22+, TypeScript, pnpm workspace\n- **Build**: Turbo for monorepo orchestration and caching\n- **Messaging**: XMTP Protocol for decentralized messaging\n- **AI**: OpenRouter API and Vercel AI SDK for natural language processing\n- **Web3**: Viem for Ethereum interactions, Coinbase AgentKit for DeFi\n- **Development**: Biome for linting and formatting\n- **Testing**: Vitest for fast unit and integration tests\n\n### Environment Variables\n\nKey environment variables for agent operation:\n\n```env\n# Required\nOPENROUTER_API_KEY=\"your_openai_api_key\"  # For AI integration\nXMTP_WALLET_KEY=\"0x...\"                        # XMTP wallet private key\nXMTP_ENV=\"dev\"                           # dev or production\n\n# Optional\nPORT=\"8454\"                              # Port for the agent server\nXMTP_DB_ENCRYPTION_KEY=\"...\"                     # For secure data encryption\n```\n\n## 🚀 Deployment\n\nDeploy your Hybrid agent anywhere Node.js runs:\n\n### Build and Deploy\n\n1. **Build the project**:\n```bash\npnpm build\n```\n\n2. **Deploy to any Node.js hosting provider**:\n   - Vercel\n   - Railway\n   - Render\n   - Heroku\n   - DigitalOcean\n   - AWS Lambda\n   - Google Cloud Functions\n\n### Environment Variables\n\nMake sure these environment variables are configured in your deployment:\n- `OPENROUTER_API_KEY` - Your AI API key\n- `XMTP_WALLET_KEY` - XMTP wallet private key\n- `XMTP_ENV` - dev or production\n- `PORT` - Port for the agent server (optional)\n\n## 🧪 Testing\n\n### Run Tests\n\n```bash\npnpm test\n```\n\n### Manual Testing\n\n1. Start your agent: `pnpm dev`\n2. Send XMTP messages to test your agent's responses\n3. Verify your custom filters and AI integration work as expected\n\n## 📚 API Reference\n\n### Core Classes\n\n- **Agent**: Main agent class for creating and configuring XMTP agents\n- **MessageListenerConfig**: Configuration for message filtering and processing\n- **Reaction**: Type for handling XMTP reactions\n\n### Key Methods\n\n- `agent.listen()`: Start listening for XMTP messages with custom filters\n- `filter()`: Define which messages your agent should respond to\n- `processMessage()`: Handle incoming XMTP messages\n- `sendResponse()`: Send responses back to users\n\n### Message Types\n\nHybrid supports all XMTP message types:\n- **Text Messages**: Standard text content\n- **Reactions**: 👍, ❤️, and custom reactions\n- **Replies**: Threaded conversations\n- **Custom Content**: Any XMTP-supported content type\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## 📄 License\n\nISC License - see LICENSE file for details\n\n## 🏗️ Architecture\n\nThis project uses a monorepo structure with multiple packages and supporting directories:\n\n```\nhybrid/\n├── config/                # Shared configuration (biome, tsconfig)\n├── examples/\n│   └── basic/             # Basic agent example implementation\n├── packages/\n│   ├── core/              # Main agent framework library (published as \"hybrid\")\n│   ├── cli/               # Command-line interface (bin: \"hybrid\")\n│   ├── create-hybrid/     # Project scaffolding tool (npm create hybrid)\n│   ├── ponder/            # Ponder plugin and event forwarder\n│   ├── types/             # Shared TypeScript types (@hybrd/types)\n│   ├── utils/             # Utilities (@hybrd/utils)\n│   └── xmtp/              # XMTP client and resolvers (@hybrd/xmtp)\n├── scripts/               # Repo scripts (version bump, etc.)\n└── site/                  # Docs website\n```\n\n## 🆘 Support\n\n- **Documentation**: Check the `/docs` directory\n- **Issues**: Create GitHub issues for bugs\n- **Discussions**: Use GitHub discussions for questions\n\nBuilt with ❤️ using modern web3 technologies and natural language processing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fian%2Fhybrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fian%2Fhybrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fian%2Fhybrid/lists"}