Understanding the BuilderIO/agent-native Codebase: Root Files Explained

The root files of the BuilderIO/agent-native repository establish an action-first TypeScript monorepo where AI agents and UI components share identical business logic through SQL-backed state, enforced by automated guard scripts and strict architecture contracts.

The BuilderIO/agent-native repository serves as the foundation for Builder.io's agent-native framework, combining a full-stack TypeScript monorepo with reusable templates and a powerful action-first architecture. Understanding these root files is essential for navigating how the system enables seamless parity between AI agents and user interfaces while maintaining strict code quality standards.

Root Configuration Files

The foundation of the repository rests on three critical configuration files that define the runtime environment, workspace metadata, and application manifest.

package.json

The package.json file declares the monorepo's workspace boundaries and orchestration scripts. It pins the Node.js engine to >=22.22.0 and establishes core dependencies including hono for the server framework and kysely for SQL query building. The scripts section exposes commands like pnpm dev, pnpm test, and pnpm guards, which internally delegate to the TypeScript scripts in the scripts/ directory.

app.json

The app.json file functions as a Vite/Next.js-style application manifest consumed by the development server and Netlify builds. It declares entry points, route prefixes, and environment-specific flags such as desktop and electron that alter the build target. This file determines how the Nitro server boots and which frontend assets are served in different deployment contexts.

agent-native.json

The agent-native.json file provides workspace-level metadata consumed by the @agent-native/core CLI. It catalogs available template packages, configures skill synchronization settings, and defines the Local File Mode flag—a critical setting that instructs the runtime to treat repository files as a live data source during development.

Policy and Architecture Contracts

Beyond configuration, the root contains enforceable policy documents that govern how code is written and maintained.

AGENTS.md

The AGENTS.md file serves as an "always-on" policy document for autonomous agents modifying the repository. It enforces the Architecture Contract, which mandates four non-negotiable constraints: SQL-backed state persistence via Drizzle, actions-first business logic, shadcn/ui for interface components, and zero unscoped database queries. This document also prescribes branch safety rules and version-bumping discipline, ensuring that automated agents cannot bypass structural safeguards.

DEVELOPMENT.md

The DEVELOPMENT.md file provides the contributor handbook for building, testing, and debugging. It details the "lazy" versus "eager" development modes—where lazy mode hot-reloads only changed modules while eager mode pre-compiles the entire dependency graph. The file also documents the end-to-end testing harness using Playwright and the specific guard scripts that must pass before committing.

Automation Scripts

The scripts/ directory contains TypeScript and JavaScript orchestration tools that enforce code quality and automate workflows.

workspace-run.ts

The scripts/workspace-run.ts file serves as the entry point for pnpm test, pnpm typecheck, and pnpm guards. It coordinates parallel execution across the monorepo packages, ensuring that linting, type checking, and test suites run in the correct dependency order. This script abstracts the complexity of running commands across the packages/core, packages/dispatch, and other independent publishable units.

Guard Scripts

Guard scripts enforce architectural constraints at build time. For example, scripts/guard-no-unscoped-queries.mjs statically analyzes the codebase to ensure every SQL query includes an access filter, preventing insecure data exposure. These guards run automatically in CI and can be invoked locally via commands like pnpm guard:no-unscoped-queries.

Skill Synchronization

The scripts/sync-workspace-core-skills.ts and sync-plan-skills.ts files maintain alignment between the framework's codebase and the AI agent's instruction set. Running pnpm sync:workspace-skills updates the .agents/skills directory, ensuring that agents operating on the repository have the latest contextual knowledge of the framework's capabilities.

Monorepo Packages and Templates

The root directory organizes functional code into two distinct categories: reusable packages and starter templates.

packages/

The packages/ directory contains independent, publishable modules that implement the runtime infrastructure:

• packages/core – Exports defineAction, useActionQuery, and useActionMutation for the action-first SDK
• packages/dispatch – Provides background job orchestration capabilities
• packages/scheduling – Implements cron-like task execution
• packages/pinpoint – Handles analytics and observability

templates/

The templates/ directory contains fully-featured example applications such as clips, plan, and analytics. Each template is a standalone Next.js-style application that demonstrates the framework's four-area pattern (UI + actions + skills + state) out of the box. Unlike packages, templates are not published to npm; they serve as boilerplate for new projects.

CI/CD Configuration

The .github/workflows/ directory houses automation pipelines that enforce quality gates and generate documentation. These workflows run the guard checks and test suites on every pull request, automatically generate visual plan recaps for code reviews, and manage the auto-publish pipeline for package releases.

Code Examples

Defining an Action

Actions represent the single source of truth for business logic. In actions/email-reply.ts, you define an action using the core SDK:

import { defineAction } from '@agent-native/core';
import { z } from 'zod';
import { db } from '../db';
import { replies } from '../schema';

export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
  },
});

Consuming Actions in React Components

UI components invoke the same actions through typed hooks, ensuring agent-UI parity:

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

export function ReplyForm() {
  const reply = useActionMutation('email-reply');
  
  const onSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    await reply.mutateAsync({ 
      emailId: '123', 
      body: formData.get('body') as string 
    });
  };
  
  return (
    <form onSubmit={onSubmit}>
      <textarea name="body" required />
      <button type="submit">Send Reply</button>
    </form>
  );
}

Running Quality Guards Locally

Before committing, verify that your SQL queries meet safety standards:

pnpm guard:no-unscoped-queries

This executes scripts/guard-no-unscoped-queries.mjs to validate that all database queries include proper tenant scoping filters.

Synchronizing Agent Skills

After modifying framework capabilities, update the agent's knowledge base:

pnpm sync:workspace-skills

This triggers scripts/sync-workspace-core-skills.ts to regenerate the skill definitions in .agents/skills, ensuring that AI agents working with the codebase understand the latest API surface.

Summary

• The BuilderIO/agent-native root files establish a TypeScript monorepo with strict architectural contracts enforced through AGENTS.md and automated guard scripts.
• Configuration files (package.json, app.json, agent-native.json) define the runtime environment, CLI metadata, and build manifests, requiring Node.js >=22.22.0.
• The action-first pattern centralizes business logic in actions/ directories, consumed by both React components via useActionMutation and AI agents via tool interfaces.
• SQL-backed state persists through Drizzle ORM, with useDbSync() broadcasting changes to keep UI and agent state synchronized.
• Guard scripts (guard-no-unscoped-queries.mjs) and skill synchronization (sync-workspace-core-skills.ts) automate code quality and documentation maintenance.

Frequently Asked Questions

What is the Architecture Contract in the BuilderIO/agent-native codebase?

The Architecture Contract is a policy defined in AGENTS.md that mandates four structural requirements for all code in the repository: SQL-backed state persistence using Drizzle, business logic encapsulated in actions via defineAction, UI components built with shadcn/ui, and zero unscoped database queries. This contract ensures that both human developers and AI agents maintain consistent architectural patterns across the codebase.

How do guard scripts enforce code quality in the repository?

Guard scripts are automated checks located in scripts/guard-*.mjs that run during CI and can be executed locally via pnpm guards. For example, scripts/guard-no-unscoped-queries.mjs statically analyzes the codebase to verify that every SQL query includes tenant access filters, preventing data leakage vulnerabilities. These scripts act as automated reviewers that block commits violating architectural constraints.

What is Local File Mode in agent-native.json?

Local File Mode is a configuration flag in agent-native.json that instructs the @agent-native/core runtime to treat local repository files as a live data source rather than a compiled bundle. When enabled, the framework reads templates, skills, and actions directly from the filesystem, enabling instant reflection of code changes without rebuilds during the pnpm dev lazy development mode.

How do templates differ from packages in the monorepo structure?

Packages (packages/core, packages/dispatch, etc.) are independent, versioned modules published to npm that provide the framework's runtime SDK and infrastructure services. Templates (templates/clips, templates/plan, etc.) are complete, standalone example applications that demonstrate implementation of the four-area pattern (UI + actions + skills + state) but are not published as libraries—they serve as starting points for new projects.

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