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

> Explore the BuilderIO/agent-native root directory for a complete TypeScript monorepo structure guide. Discover manifest files, workspace config, and documentation for framework packages and applications.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: guide
- Published: 2026-07-01

---

**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`](https://github.com/BuilderIO/agent-native/blob/main/README.md), [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md), [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)
- **Configuration**: [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json), [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml), [`app.json`](https://github.com/BuilderIO/agent-native/blob/main/app.json), [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)
- **Tooling**: `.gitignore`, `.prettierignore`, [`.oxlintrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxlintrc.json), `.nvmrc`
- **Workspace directories**: `packages/`, `templates/`, `scripts/`, `docs/`, `plans/`, `e2e/`, `.github/`

## Configuration Files

### package.json

The root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/app.json) – Contains basic metadata such as the application name and version.
- [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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:

```bash

# Clone and install

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

```

The `postinstall` hook in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) triggers [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/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:

```bash

# 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`:

```javascript
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`](https://github.com/BuilderIO/agent-native/blob/main/package.json):

```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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/ci.yml)) runs linting (oxlint), formatting checks (oxfmt), TypeScript type-checking via [`scripts/workspace-run.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/workspace-run.ts), unit tests, and guard validations.

The [`auto-publish.yml`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/package.json) (scripts), [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) (workspace bounds), [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) (CLI manifest), and [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/app.json) contains basic application metadata like name and version consumed by the CLI, while [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/.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`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml), which allows pnpm to treat these directories as a unified workspace while keeping the top level clean and navigable.