How openagentsinc/openagents works
Based on our analysis of both the file tree and the README, the project is clearly a cross‐platform monorepo for an AI Agents platform (OpenAgents) that supports several client types. The key purpose is to enable a collaborative agentic chat experience using open protocols, with distinct applications for web (chatserver and coder for desktop) and mobile (onyx for chat and bitcoin wallet functionality), plus various shared libraries that define the agents and core business logic.
Main Components
• Apps (Client Applications):
• Chatserver: This is the backend AI SDK chat API service.
• Coder: The desktop application (a drop-in replacement for a previous tool) built using React and TypeScript, featuring chat UI, thread history, and MCP integration.
• MCP GitHub Server: A remote server that provides GitHub tools and MCP integration.
• Onyx: The mobile app that not only provides chat functionality but also acts as a Bitcoin wallet.
• Shared Packages:
• Agents: Contains definitions and reusable agent logic.
• Core: Provides shared core logic, utility functions, and integration with MCP (message control protocol) components.
• UI: Contains reusable UI components for chat, buttons, cards, toasts, and other visual elements.
• Documentation: Although not part of runtime architecture, the docs folder gives insight into integration, troubleshooting, and design considerations.
• External Services & Integrations:
• Cloudflare stack for the backend (including Durable Objects for the Agents).
• Auth (with better-auth).
• Vercel AI SDK for additional AI integrations.
• External wallets (Breez SDK, Spark wallet) for Bitcoin/Lightning network operations.
• Open protocols integration (MCP, Nostr network) for interoperability.
Relationships and Interactions
• Client Applications (coder, onyx) interface with:
• The shared packages (agents, core, ui) to render consistent UIs and reuse business logic.
• The backend services such as the Chatserver API and MCP GitHub server.
• Chatserver and MCP GitHub server are backend services that handle API requests, agent interactions, and MCP integrations.
• Agents run as long-lived processes (for instance, on Cloudflare’s Durable Objects) and communicate with both the backend services and client applications.
• There is an interoperability link between chat clients (e.g., coder, onyx) and external protocols (MCP and Nostr) that enables actions like chat-based commands and integration with GitHub workflows.
• The shared core logic is used across both client and server components to standardize communication, command parsing/execution, error handling, and more.
Important Architectural Patterns and Design Principles
• Monorepo Structure: Emphasizes code reuse across diverse client implementations and servers.
• Separation of Concerns: Each app (chatserver, coder, mcp-github-server, onyx) has clearly delineated responsibilities (backend API vs. frontend UI vs. mobile wallet).
• Reusable Shared Libraries: Agent definitions, core logic, and UI components are built as separate packages to be consumed by multiple applications.
• Cross-Platform Development: Use of React/React Native and TypeScript to ensure consistency across desktop, mobile, and web.
• Integration with External Protocols: MCP, Nostr, and external wallet integrations that define the data flow between internal components and third-party services.
• Cloudflare Backend Architecture: Utilization of Cloudflare’s capabilities (including Durable Objects) for running long-lived agent processes.
Relevant Technologies and Frameworks
• Frontend: React, React Native, TypeScript.
• Backend: Cloudflare (Durable Objects, wrangler configuration), Node (for chatserver and MCP GitHub server).
• Testing: Jest, Playwright, Vitest (as indicated by the test configurations found in the apps).
• Build & Config: Vite and TypeScript configuration files across the apps and packages.
• Wallet/Payment Integration: Breez SDK (for onyx) and considerations for Spark wallet integration.
• Other: Better-auth for authentication, and integration with Vercel AI SDK.