BuilderIO/agent-native Root Directory: Complete Monorepo Structure Guide

The root directory of the BuilderIO/agent-native repository contains the manifest files, workspace configuration, and documentation needed to orchestrate a TypeScript monorepo of framework packages and production-ready template applications.

The BuilderIO/agent-native project is organized as a compact, deliberate monorepo. Its top-level folder serves as the central command hub, containing the configuration files, development guides, and pnpm workspace settings that wire together the core framework code in packages/ and the runnable SaaS templates in templates/.

Root Directory Overview

The agent-native monorepo root is intentionally minimal. It relies on a small set of configuration files to define the workspace behavior, tooling constraints, and development workflows. Rather than cluttering the top level with source code, the root acts as an orchestration layer that declares where the actual code lives and how the pieces fit together.

Key top-level items fall into four categories:

• Documentation: README.md, DEVELOPMENT.md, AGENTS.md
• Configuration: package.json, pnpm-workspace.yaml, app.json, agent-native.json
• Tooling: .gitignore, .prettierignore, .oxlintrc.json, .nvmrc
• Workspace directories: packages/, templates/, scripts/, docs/, plans/, e2e/, .github/

Configuration Files

package.json

The root package.json defines repo-wide npm scripts, development dependencies, Node engine requirements, and pnpm-specific overrides. It is the entry point for all build and test operations.

Critical scripts include:

• pnpm install – Installs dependencies across the monorepo using the workspace configuration.
• pnpm run prep – Runs the full validation suite including formatting, linting, type-checking, and tests.
• pnpm run dev:all – Starts all templates simultaneously for integration testing.
• pnpm run guards – Executes security and quality guard scripts.

pnpm-workspace.yaml

This file declares the monorepo boundaries. It explicitly lists which directories contain packages (packages/*) and which contain template applications (templates/*). It also defines a catalog of allowed dependencies to ensure version consistency across the workspace.

When you run pnpm install, pnpm reads this file to determine which subdirectories to include in the workspace graph.

app.json and agent-native.json

These JSON manifests are consumed by the Agent-Native CLI:

• app.json – Contains basic metadata such as the application name and version.
• agent-native.json – A workspace-level manifest that describes how the CLI should treat directories, distinguishing between core packages and template apps.

Documentation Entry Points

Three markdown files provide the primary documentation for contributors and users.

README.md

The README.md serves as the project pitch. It contains a high-level description, a quick-start code snippet, and an index of official templates available in the templates/ directory.

DEVELOPMENT.md

Located at the repository root, DEVELOPMENT.md is the canonical development guide. It details prerequisites (Node version, pnpm installation), common commands, and the full workspace layout. This is the first file new contributors should read after the README.

AGENTS.md

AGENTS.md defines the framework-level rules and architecture contract. It includes the skill index, project map, and architectural decisions that govern how agents interact with the framework.

Development Workflow and Scripts

Workspace Bootstrapping

The development environment is initialized through a standard pnpm workflow that leverages the root configuration files:

# Clone and install

git clone https://github.com/BuilderIO/agent-native.git
cd agent-native
pnpm install

The postinstall hook in package.json triggers scripts/prebuild-workspace-packages.ts, which builds internal packages before any template compilation begins. This ensures that the framework code is ready before the apps that depend on it.

Running Templates

You can run individual templates or the entire suite:

# Run a single template (e.g., the mail app)

pnpm --filter mail dev

# → Vite dev server starts at http://localhost:3000

# → Backend Nitro server runs on http://localhost:3001

# Run all templates together

pnpm run dev:all

Guard Scripts

Security and quality invariants are enforced by guard scripts located in scripts/guard-*.mjs. These are invoked via pnpm run guards or automatically in CI.

For example, to add a custom guard that scans for hard-coded API keys, create scripts/guard-no-public-keys.mjs:

import { readFileSync, readdirSync } from 'fs';
import { join } from 'path';

const ROOT = process.cwd();
const suspicious = /['"`]?(?:sk|pk|api[_-]?key)['"`]?:\s*['"`][A-Za-z0-9._-]+['"`]/i;

function scan(dir) {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) scan(full);
    else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
      const content = readFileSync(full, 'utf8');
      if (suspicious.test(content))
        console.error(`Possible secret in ${full}`);
    }
  }
}
scan(ROOT);

Then add it to package.json:

"guard:no-public-keys": "node scripts/guard-no-public-keys.mjs"

Core Workspace Directories

packages/

The packages/ directory contains the framework runtime and supporting libraries. This includes the core dispatch engine, UI library (code-agents-ui), scheduling primitives, and other shared utilities. Each subdirectory is a distinct package referenced by pnpm-workspace.yaml.

templates/

The templates/ folder houses production-ready sample applications. Each template (such as mail, calendar, clips, and plan) is a fully functional SaaS-style app with its own package.json, database schema, and UI. These serve as both usage examples and starting points for new projects.

Supporting Directories

• scripts/ – TypeScript and Node.js utilities for building, testing, guarding, and syncing skills.
• docs/ – Source markdown for the documentation site, rendered by the @agent-native/docs package.
• plans/ – Markdown-based visual-plan artifacts used by the visual-plan skill for UI diagrams and diff views.
• e2e/ – Playwright-based end-to-end tests for real-world user flows across templates.
• .github/ – GitHub Actions workflows for CI, releases, auto-merge, and guard checks.

CI/CD Configuration

The .github/workflows/ directory contains automation pipelines. The primary workflow (ci.yml) runs linting (oxlint), formatting checks (oxfmt), TypeScript type-checking via scripts/workspace-run.ts, unit tests, and guard validations.

The auto-publish.yml workflow ensures that any merged PR passing all guards automatically publishes updated package versions using changeset scripts (pnpm run changeset:*).

Summary

• The BuilderIO/agent-native root directory is a minimal orchestration layer that configures the monorepo workspace.
• Key files: package.json (scripts), pnpm-workspace.yaml (workspace bounds), agent-native.json (CLI manifest), and DEVELOPMENT.md (contributor guide).
• Key directories: packages/ (framework code), templates/ (sample apps), scripts/ (build utilities), and e2e/ (Playwright tests).
• Bootstrapping requires only pnpm install, which triggers scripts/prebuild-workspace-packages.ts to prepare the workspace.
• Guard scripts in scripts/ enforce security invariants and run automatically in CI.

Frequently Asked Questions

What is the difference between app.json and agent-native.json?

app.json contains basic application metadata like name and version consumed by the CLI, while agent-native.json is a workspace-level manifest that tells the Agent-Native CLI how to treat different directories—specifically which folders contain templates versus which contain core packages.

How do I run a specific template from the root directory?

Use pnpm's filter command to target the template by its folder name. For example, pnpm --filter mail dev starts the mail template's Vite dev server on port 3000 and its Nitro backend on port 3001. You can also run pnpm run dev:all to start every template simultaneously for integration testing.

Where are the guard scripts located and how do they run?

Guard scripts reside in the scripts/ directory with the naming pattern guard-*.mjs. They are executed via pnpm run guards or automatically as part of the CI pipeline defined in .github/workflows/ci.yml. These scripts enforce security invariants such as preventing unscoped database queries or leaked environment credentials.

Why is there no source code in the root directory?

The repository follows a strict separation of concerns: the root contains only configuration and documentation, while all source code lives in packages/ (framework libraries) or templates/ (application code). This structure is declared in pnpm-workspace.yaml, which allows pnpm to treat these directories as a unified workspace while keeping the top level clean and navigable.

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