OpenAgents is a platform for Bitcoin-powered AI agents built with Effect and open protocols.
Our flagship chat application showcases AI agents that can interact through the Nostr protocol, accept Bitcoin payments via Lightning, and leverage multiple AI providers for intelligent responses.
This monorepo contains our fully Effect-based architecture with comprehensive type safety, streaming support, and production-ready AI integrations.
OpenAgents is built as a monorepo using pnpm workspaces, with a clean separation between reusable packages (libraries) and user-facing applications. The architecture emphasizes type safety through TypeScript and Effect, deterministic agent identities via Bitcoin standards, and local-first AI inference.
- Fully Effect-Based: Complete Effect integration throughout the stack - no Promise/async mixing
- Streaming-First: SSE-based streaming with proper Effect Stream to Web Stream conversion
- Multi-Provider AI: Unified interface for Cloudflare (free), OpenRouter (100+ models), and Ollama (local)
- Bitcoin-Native: Agents use deterministic identities (NIP-06) with Lightning Network payments
- Type-Safe Services: Effect Services with Layer-based dependency injection
- Schema-Driven: Runtime validation with
@effect/schemafor all API contracts - Production-Ready: Comprehensive error handling, proper resource management, and monitoring
┌─────────────────────────────────────────────────────────────────┐
│ Applications │
├─────────────────────────────────────────────────────────────────┤
│ openagents.com │
│ (Next.js Chat App with AI & Bitcoin - Convex Backend) │
├─────────────────────────────────────────────────────────────────┤
│ Core Packages │
├─────────────────┬───────────────┬───────────────────────────────┤
│ sdk │ nostr │ relay │
│ (Agent Runtime) │ (Protocol) │ (Database & Events) │
├─────────────────┴───────────────┴───────────────────────────────┤
│ AI & Testing Packages │
├────────────────────────────┬────────────────────────────────────┤
│ ai │ autotest │
│ (Provider Abstraction) │ (Browser Automation) │
├────────────────────────────┴────────────────────────────────────┤
│ Demo Packages │
├─────────────────────────────────────────────────────────────────┤
│ cli │
│ (Demo Interface) │
└─────────────────────────────────────────────────────────────────┘
- SDK → Nostr: NIP-06 deterministic key derivation for agent identities
- AI → Effect Streams: Streaming AI responses with proper layer management
- OpenAgents.com → Convex: Main app uses Convex for backend, not packages
- Relay → PlanetScale: MySQL database with Drizzle ORM (future use)
# Install dependencies
pnpm i
# Set up git hooks for quality checks
pnpm setup-hooks
# Build all packages (required before testing)
pnpm build
# Run tests
pnpm test
# Type checking
pnpm check
# Lint code
pnpm lint
# Generate Effect exports (not for UI package!)
pnpm --filter=@openagentsinc/sdk codegen@openagentsinc/sdk- Bitcoin-powered agent runtime with Lightning payments@openagentsinc/nostr- Effect-based Nostr protocol with NIP support@openagentsinc/relay- Database layer with PlanetScale MySQL integration
@openagentsinc/ai- Multi-provider AI abstraction (Cloudflare, OpenRouter, Ollama)- Cloudflare: Free models including Llama 4 Scout
- OpenRouter: 100+ premium models (GPT-4, Claude, etc.)
- Ollama: Local inference for privacy
@openagentsinc/autotest- Browser automation and visual testing@openagentsinc/cli- Command-line interface (demo)
openagents.com- Production chat application (MVP)- Next.js 14 with App Router and TypeScript
- Convex backend for real-time data sync
- Arwes UI components for cyberpunk theme
- GitHub OAuth authentication
- Tool-based artifact creation system
Before working on this codebase, you MUST read the relevant guides:
- Effect Architecture Guide - Core Effect patterns and Psionic framework
- Streaming Architecture Guide - Critical SSE streaming patterns
- AI Provider Integration Guide - Adding and configuring AI providers
- Language Model Integration Guide - Model configuration and UI
- Chat Layout Architecture Guide - Chat interface structure and styling
- Effect Quick Reference - Common patterns and anti-patterns
- CLAUDE.md - Coding agent instructions and forbidden patterns
- Database Migration Guide - PlanetScale schema management
- Autotest Documentation - Browser testing framework
- Server-Sent Events (SSE) for real-time AI responses
- Proper Effect Stream to Web Stream conversion
- Anti-buffering headers for CDN compatibility
- Error recovery and timeout handling
- Cloudflare Workers AI: Free tier with Llama models
- OpenRouter: Access to 100+ models with single API
- Ollama: Local models for privacy-conscious users
- Unified streaming interface across all providers
- No
async/awaitor Promises in route handlers - Proper service layer composition
- Type-safe error handling with tagged errors
- Resource management with finalizers
- Deterministic agent identities (NIP-06)
- Lightning Network payment capabilities
- Nostr protocol for decentralized communication
- Agent-to-agent messaging support
# Clone the repository
git clone https://github.com/OpenAgentsInc/openagents.git
cd openagents
# Install dependencies
pnpm install
# Set up git hooks
pnpm setup-hooks
# Build all packages
pnpm build
# Run tests
pnpm test
# Start development
cd apps/openagents.com && pnpm dev # Main app on :3000Create .env files based on .env.example:
# Required for AI features
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_API_KEY=your_api_key
# Optional for premium models
OPENROUTER_API_KEY=your_api_key
# Database (PlanetScale)
DATABASE_URL=mysql://...- Read the architecture guides (seriously, read them!)
- Follow Effect patterns - no Promise mixing
- Run tests before pushing
- Update documentation for new features
MIT - See LICENSE for details
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
