​
Our Core Architecture

Cedar-OS bridges the gap between AI agents and React applications, providing a comprehensive framework for AI agents to read, write, and interact with your application state, just like users can. Cedar-OS Architecture Diagram Cedar-OS Architecture Diagram

​
Zustand State Management

Let’s say you want an AI to be able to read and write different parts of your react app. For example, you’re making an AI-native email, and you want it to be able to help with drafts and categorise emails. You have an AI chat on the side that the user can ask it to do things. You’d find some immediate problems with this:
  1. Component-scoped State: React typically has state inside of the component that uses it. This totally makes sense, and makes for a really great developer experience where you can combine logic and rendering together! But this also means that floating up and collecting different states across the application to the AI involves a lot of scoping problems, prop drilling, and messy re-render optimisation.
  2. Lack of Predefined Interactions: The AI needs much more predefined ways of working with state! How does it interpret what this state means? How does it know how it can and should change it?
  3. State Lifecycle Issues: State disappears when the component is unmounted, or might have never loaded in! AI should get to make changes, then navigate the user to see those changes.
Cedar fixes this by:
  1. Register States: Each “RegisterCedarState” acts like a portal the agent can reach the specific state. You don’t need to worry about contexts, their scopes, and most importantly the fact that if one context field changes, everything that subscribes to it changes.
  2. States for agents: Our types support agent understanding and allow you to create custom setters that allow the agent to interact in predefined, safe ways.
  3. Persistent State Registration: State can be registered so the agent can see the contents even if the user doesn’t have the component rendered in that moment, and backend loading behaviour can be configured.

​
Cedar’s Zustand Implementation

  • Centralized Data Store: It stores all the data the agent needs in one centralised place
  • State Persistence: It persists state across component lifecycles
  • Override Capability: It allows you to override any internal function simply by registering a slice with the same field key
  • Optimized Hooks: We provide optimised hooks (and every internal zustand slice)
  • Pre-built Components: We create components that use these hooks and internal state
  • Complete Solutions: We put together these components into completed functionality, so you can get a working chat in one line

​
Hooks Layer - The Foundation

At the base, we provide optimized hooks that connect directly to our Zustand store. Examples:
  • useCedarState: Access and modify registered state with type safety
  • useTypedAgentConnection: Manage AI agent connections with full typing
  • useCedarEditor: Rich text editing with AI-aware features
  • useMessageRenderer: Handle streaming messages and custom components
These hooks abstract away the complexity of state management, context, and real-time updates while maintaining full type safety and performance optimization. You can of course create your own hooks that plug into the Zustand store.

​
Components Layer - Shadcn-Style Customization

Our component layer adopts the shadcn/ui philosophy of copy-and-own rather than traditional npm packages. Why Copy-and-Own Works Better for AI Components:
  • Full Customization: You own the component code, so you can modify styling, behavior, and logic without fighting against package constraints
  • No Version Lock-in: Updates are opt-in. You choose when and what to update, preventing breaking changes from disrupting your AI experiences
  • Transparent Implementation: You can see exactly how components work with AI state, making debugging and customization straightforward
Component Examples:
  • ChatInput - AI-aware input with mentions and context
  • StreamingText - Real-time text rendering with typewriter effects
  • MessageRenderer - Renders different messages with unique styling or interactivity.
  • VoiceIndicator - Visual feedback for voice interactions
Each component is designed to be sophisticated out-of-the-box while remaining completely customizable to your design system and requirements.

​
Complete Solutions - One-Line AI Experiences

At the top layer, we provide complete, production-ready AI experiences. We can provide sophisticated solutions like this because you own the code, and so you can customise it however you want. Example:
  • <FloatingCedarChat />: Floating chat interface that can be summoned anywhere. This combines <ChatInput />, <ContextBadge />, <ChatMessages />, and positional Containers like <FloatingContainer /> to create a floating chat.
The Power of This Architecture:
  1. Start Simple: Drop in a complete solution like CedarCopilot and FloatingCedarChat and have AI working in minutes
  2. Customize Gradually: Customise individual components as your needs evolve
  3. Go Deep: Use hooks directly for completely custom AI experiences
  4. Never Hit Walls: Since you own all the code, there are no limitations on what you can build.