Builder.io Agent Native Project Structure: A Complete Guide to the Monorepo Architecture

The Builder.io Agent Native project is organized as a monorepo implementing a four-area architecture (UI, actions, skills/instructions, and application state) with distinct top-level directories for app/, actions/, packages/, templates/, and .agents/ that enable AI agents and React components to share the same operational surface.

The BuilderIO/agent-native repository provides a full-stack framework where AI agents and UI components operate on identical data and action primitives. Understanding the Builder.io Agent Native project structure is essential for building agent-driven applications that maintain a single source of truth across human and automated interfaces. The codebase enforces a strict architectural contract through AGENTS.md, ensuring every feature implementation touches the four required architectural areas consistently.

Top-Level Directory Organization

The repository root contains seven primary directories that separate concerns between frontend rendering, server logic, reusable libraries, and agent instructions:

Directory	Purpose	Key Technologies
app/	React frontend with CSR for authenticated pages and SSR for public pages	shadcn/ui, AgentComposerFrame, useActionQuery
actions/	Server-side action definitions exposing operations to both UI and agents	defineAction, Zod validation, Drizzle ORM
server/	Nitro API routes, plugins, and database configuration	Nitro framework, SQL endpoints
packages/	Reusable NPM libraries including core runtime and dispatch logic	TypeScript, independent versioning via changesets
templates/	Boilerplate applications demonstrating concrete Agent Native implementations	Vite, Vitest, ssr-entry.ts
.agents/	Skill definitions and instruction files guiding AI self-modification	Markdown skill files, plugin definitions
docs/	End-user documentation rendered within the application	Static content package

The monorepo configuration is driven by pnpm-workspace.yaml at the repository root, which defines workspace packages for independent dependency management and versioning.

The Four-Area Architectural Contract

Every feature in the Builder.io Agent Native project structure must conform to the four-area checklist defined in AGENTS.md:

1. UI Components – React components in app/ that render data and capture user input
2. Actions – Server-side functions in actions/ that mutate or query application state
3. Skills/Instructions – Agent guidance files in .agents/skills/ that define how AI modifies the codebase
4. Application State – SQL-backed storage schemas accessible via Drizzle ORM

This contract ensures that AI agents can understand and modify the application safely, as every data operation flows through the centralized action surface rather than ad-hoc API endpoints.

Package Architecture and Reusable Libraries

The packages/ directory contains modular libraries that power the framework's runtime capabilities. Each package maintains its own tsconfig.json, test suite, and changelog for independent versioning:

• packages/core/ – Type definitions, runtime utilities, and action framework primitives including defineAction
• packages/dispatch/ – Task queue implementation and background job processing logic
• packages/scheduling/ – Temporal primitives for time-based agent operations
• packages/pinpoint/ – Performance-focused utilities for optimization
• packages/shared-app-config/ – Cross-cutting configuration management
• packages/code-agents-ui/ – UI components specifically for agent interaction interfaces

These packages expose typed APIs that both the main application and template projects consume, ensuring consistency across different Agent Native implementations.

Template Applications and SSR Entry Points

The templates/ directory provides ready-to-run example applications that demonstrate specific Agent Native patterns:

• templates/dispatch/ – Task queue management interface
• templates/chat/ – Conversational agent UI patterns
• templates/brain/ – Knowledge base and memory management
• templates/macros/ – Automated workflow execution

Each template contains its own vite.config.ts, vitest configuration, and an ssr-entry.ts file that defines the server-side rendering entry point. Templates also include shared/api.ts and shared/types.ts files providing typed API helpers consistent with the main application's action surface.

Agent-Driven Development with Skills

The .agents/ directory enables the framework's meta-capability: AI agents that can safely modify the codebase itself. This directory contains:

• .agents/skills/*/ – Granular instruction directories (e.g., upgrade-agent-native/) containing SKILL.md files that specify exact steps for code modification
• .agents/plugins/*/ – Plugin definitions extending agent capabilities

Skills follow a structured format that maps to the four-area architecture, ensuring that when an agent modifies code, it updates the UI components, actions, skill instructions, and database schema in concert. For example, the upgrade-agent-native skill guides AI through the safe migration of workspace configurations to the latest framework version.

Practical Implementation Examples

Calling Server Actions from React Components

UI components interact with the unified action surface through React hooks exported from the core package:

import { useActionMutation } from '@agent-native/core/actions';

function NewResourceButton() {
  const createResource = useActionMutation('createResource');

  const handleClick = async () => {
    await createResource.mutateAsync({ 
      name: 'My Resource', 
      type: 'document' 
    });
  };

  return <button onClick={handleClick}>Create Resource</button>;
}

The useActionMutation hook provides the same action interface that agents invoke as tools, ensuring identical validation and access control regardless of the caller.

Defining Type-Safe Server Actions

All mutating logic resides in the actions/ directory using the defineAction helper:

// actions/createResource.ts
import { defineAction } from '@agent-native/core/actions';
import { db } from '../server/db';
import { z } from 'zod';

export const createResource = defineAction({
  input: z.object({ 
    name: z.string(), 
    type: z.string() 
  }),
  async resolve({ input, ctx }) {
    // Access-controlled write to SQL database via Drizzle
    await db.resource.create({ 
      data: { 
        ...input, 
        ownerId: ctx.userId 
      } 
    });
    return { success: true };
  },
});

Actions must use Zod for input validation, operate within a request context (ctx) containing user authentication, and interact with the database through Drizzle ORM.

Skill Definition for Feature Implementation

Skills declaratively specify how AI should implement new features:

# SKILL: add-new-resource-feature

- Update UI component at `app/components/ResourceList.tsx` to call `createResource`
- Add corresponding action in `actions/createResource.ts` using `defineAction`
- Write skill instruction under `.agents/skills/add-resource/` documenting the changes
- Ensure database schema includes the new `resource` table definition

This structured approach keeps AI modifications auditable and ensures compliance with the four-area architectural contract.

Summary

• The Builder.io Agent Native project structure organizes code into app/, actions/, server/, packages/, templates/, and .agents/ directories to separate UI, business logic, and agent instructions
• The four-area architecture (UI, actions, skills, application state) enforces that every feature is accessible to both human users and AI agents
• Server logic is centralized in actions/ using defineAction, creating a unified surface that both React hooks (useActionMutation) and AI tools consume
• The packages/ directory contains modular, versioned libraries (core, dispatch, scheduling) shared across the monorepo
• Template applications in templates/ provide working examples with independent Vite configurations and SSR entry points
• The .agents/skills/ directory enables self-modifying codebases where AI follows structured instructions to safely evolve the application

Frequently Asked Questions

What is the four-area architecture in Builder.io Agent Native?

The four-area architecture is a design contract requiring every feature to touch UI components, server actions, skill instructions, and application state. This pattern, defined in AGENTS.md, ensures that AI agents can understand and modify the codebase because all functionality is explicitly documented in skills and exposed through the unified action surface rather than hidden in frontend logic or ad-hoc endpoints.

How do UI components communicate with the database?

UI components never communicate directly with the database. Instead, they use React hooks like useActionMutation and useActionQuery from @agent-native/core/actions to call functions defined in the actions/ directory. These actions, created with defineAction, handle SQL operations via Drizzle ORM, enforce access control through the request context (ctx), and return typed responses that components consume.

What purpose does the .agents/ directory serve?

The .agents/ directory contains skill definitions that instruct AI agents on how to safely modify the codebase. Each skill lives in a subdirectory (e.g., .agents/skills/upgrade-agent-native/) and includes markdown files specifying exact steps for tasks like adding features or upgrading dependencies. This enables the framework to be self-modifying, where agents reference these instructions to ensure changes respect the four-area architectural contract.

How are packages managed within the monorepo?

The project uses pnpm workspaces defined in pnpm-workspace.yaml to manage the packages/ directory. Each package (core, dispatch, scheduling, pinpoint) maintains its own tsconfig.json, test suite, and changelog. Changesets enable independent versioning of these packages, allowing templates and the main application to depend on specific versions of the core runtime while facilitating modular updates to the framework's capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}