Building BuilderIO/agent-native from Source: Root File and Monorepo Configuration

To successfully build BuilderIO/agent-native from source, you must configure the root package.json postinstall pipeline, pnpm-workspace.yaml workspace definitions, and execute the scripts/prebuild-workspace-packages.ts orchestrator that compiles core framework packages before any template application can run.

BuilderIO/agent-native is an open-source framework that tightly couples AI agents with real web applications through a unified action surface. When building from source, understanding the root file structure and workspace configuration is essential because the repository uses a pnpm-powered monorepo where core libraries must be prebuilt before template apps can consume them. The root-level configuration files govern how the framework compiles, links, and executes across the packages/ and templates/ directories.

Root File Architecture and Workspace Configuration

The repository root contains several critical files that define the build environment and development workflow. These files establish the monorepo boundaries and ensure the core framework (@agent-native/core) is available to template applications.

package.json and Build Orchestration

The root package.json defines the workspace-wide scripts and triggers the postinstall build process. According to the source analysis, the postinstall script automatically executes scripts/prebuild-workspace-packages.ts immediately after dependency installation【/cache/repos/github.com/BuilderIO/agent-native/main/package.json#L22-L24】.

Key root scripts include:

• pnpm install – Triggers the postinstall hook to build all workspace packages
• pnpm run dev:all – Builds core then starts every template on sequential ports
• pnpm run prep – Runs formatting, type checking, tests, and CI guards locally

The postinstall script is critical because it compiles TypeScript sources in packages/core/ and other workspace members, making them importable by the template applications located in templates/mail/, templates/calendar/, and others.

pnpm-workspace.yaml and Package Linking

The pnpm-workspace.yaml file defines which directories are included in the monorepo workspace. This configuration enables the pnpm linker to resolve internal dependencies like @agent-native/core from the local packages/core/ directory rather than from the npm registry.

The workspace typically includes:

• packages/* – Core framework libraries, UI components, and dispatch services
• templates/* – Production-ready SaaS template applications (Mail, Calendar, Clips)

Without this workspace definition, the template apps would fail to resolve the local framework dependencies during the build process.

DEVELOPMENT.md and Local Setup Guidelines

The DEVELOPMENT.md file in the repository root provides the authoritative guide for prerequisites and environment setup. It documents the requirement for pnpm as the package manager and specifies the commands for running individual packages versus the entire monorepo【/cache/repos/github.com/BuilderIO/agent-native/main/DEVELOPMENT.md#L20-L30】.

Core Build Pipeline and Source Files

Building from source requires understanding how the root scripts compile the framework before applications can start.

The Prebuild Workspace Script

The scripts/prebuild-workspace-packages.ts file serves as the primary build orchestrator. This TypeScript script runs during the postinstall phase and compiles all packages in the correct dependency order. It ensures that packages/core/src/action.ts and other framework entry points are transpiled and ready for import.

The script handles the action definition surface (defineAction) that powers the entire framework, located in packages/core/src/action.ts. This file implements the unified API surface that exposes actions as React hooks, LLM tools, and CLI commands.

# Clone and initial build

git clone https://github.com/BuilderIO/agent-native.git
cd agent-native
pnpm install        # Automatically triggers prebuild-workspace-packages.ts

Template Application Structure

After the root build completes, template applications can resolve their dependencies. Each template (e.g., templates/mail/) contains its own package.json that references the workspace versions of @agent-native/core and other packages.

The templates share a common structure:

• src/schema.ts – Drizzle ORM schema definitions for SQL-backed state
• actions/ – Directory containing action definitions using defineAction
• package.json – Dependencies linked to the monorepo workspace

Development Workflow Essentials

Once root files are configured and the initial build completes, you can run specific parts of the monorepo.

Running the Entire Monorepo

To verify your build from source, use the root-level command:

pnpm run dev:all

This command builds the core framework and then launches every template application on sequential ports, allowing you to test the full integration of the agent runtime, UI components, and action definitions.

Targeting Individual Packages

For development efficiency, target specific workspace members:

# Run only the mail template

pnpm --filter mail dev

# Watch-build the core framework only

pnpm --filter @agent-native/core dev

CLI Action Execution

The root configuration enables direct action invocation via CLI:

pnpm action send-email

This command executes the send-email action defined in the templates, using the same code path that the UI and agent runtime utilize.

CI Guards and Verification

Root-level guard scripts enforce code quality and prevent deployment issues. These scripts run during pnpm run prep and in CI (.github/workflows/ci.yml):

• scripts/guard-no-drizzle-push.mjs – Prevents accidental production database pushes
• scripts/guard-no-env-credentials.mjs – Blocks hard-coded secrets
• scripts/guard-no-unscoped-queries.mjs – Ensures database queries are properly scoped

Running these guards locally ensures your source build meets repository standards before pushing changes.

Summary

• Root package.json triggers scripts/prebuild-workspace-packages.ts during postinstall to compile the framework
• pnpm-workspace.yaml defines the monorepo boundaries for packages/ and templates/ directories
• DEVELOPMENT.md provides the canonical reference for building and running from source
• Template apps depend on the prebuilt core packages; run pnpm install first to establish the workspace links
• Guard scripts in scripts/ validate the build before CI submission

Frequently Asked Questions

What is the first file I should check when building from source?

You should examine DEVELOPMENT.md immediately after cloning. This root file contains the prerequisite list, pnpm version requirements, and the command reference for building the monorepo workspace correctly.

Why does pnpm install take longer than a typical npm install?

The installation process executes scripts/prebuild-workspace-packages.ts as a postinstall hook, which compiles TypeScript sources in packages/core/ and other workspace members. This step is necessary to make the framework packages available to the template applications before you can run pnpm run dev:all.

Can I build just the core framework without the templates?

Yes. Use the filter command pnpm --filter @agent-native/core build to target only the core package. This is useful when modifying packages/core/src/action.ts or the agent runtime in packages/core/src/agent/production-agent.ts without needing to start the full template applications.

What happens if I skip the root-level guards?

Skipping the guard scripts (located in scripts/guard-*.mjs) may result in CI failures or accidental deployment issues. The guard-no-drizzle-push.mjs script specifically prevents database schema changes from being pushed to production environments during development, while guard-no-env-credentials.mjs ensures no secrets are committed to the repository.

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