How to Update Agent-Native: A Complete Guide to the Monorepo Workflow

Updating Agent-Native requires pulling the latest main branch, reinstalling pnpm workspace dependencies, running the prep script, and upgrading the CLI via npx @agent-native/core@latest.

Agent-Native is a monorepo maintained by BuilderIO that combines a core AI framework, reusable UI components, and full-stack SaaS templates. Keeping your installation current ensures access to the latest security guards, template features, and CLI capabilities. This guide walks through the exact steps to update agent-native while maintaining a consistent development environment.

Sync the Repository and Dependencies

Updating starts with the source code and dependency tree. The project uses pnpm workspaces to manage multiple packages and templates under a single root.

Pull the Latest Source

Fetch the newest commits from the upstream repository to ensure you have the latest framework code and templates.

git fetch origin
git checkout main
git pull origin main

The repository root contains the primary documentation in README.md, which outlines high-level changes and quick-start commands.

Refresh Workspace Dependencies

Agent-Native relies on pnpm workspaces defined in pnpm-workspace.yaml. After pulling updates, reinstall all packages to resolve new or upgraded dependencies across the monorepo.

pnpm install

This command ensures that every package in the workspace—including the core framework and individual templates like mail or calendar—receives the correct dependency versions specified in the lockfile.

Prepare the Development Environment

Before running applications or pushing changes, you must validate the codebase state using the built-in preparation suite.

Run the Prep Script

The root package.json defines a prep script that orchestrates formatting, type-checking, tests, and security guards. Executing this guarantees consistency across the entire workspace.

pnpm run prep

This script runs the same checks executed in the CI pipeline (see .github/workflows/ci.yml), ensuring your local environment matches the repository's quality standards.

Verify the Setup

After preparation completes, verify that type definitions and linting rules pass without errors. The prep script aggregates these checks, but you can run individual commands such as pnpm run fmt or pnpm run typecheck if you need to isolate specific issues.

Upgrade the Agent-Native CLI

The agent-native CLI is versioned independently from the repository templates. To access new skill commands, bug fixes, or the latest template picker, reinstall the core package via npx.

npx @agent-native/core@latest --version

For scaffolding new projects or adding skills to existing workspaces, use the same command pattern:

npx @agent-native/core@latest create my-app
npx @agent-native/core@latest skills add visual-plan

The CLI documentation in packages/core/README.md details available commands and skill installation procedures.

Review Breaking Changes and Changelog

New releases may introduce breaking changes, updated defaults, or new APIs like the outputSchema addition in v0.54.1. Review the version history before migrating existing code.

The core package changelog lives at packages/core/CHANGELOG.md. Check this file to determine if your current implementation requires adjustments for compatibility with the latest framework version.

Restart Your Development Server

Once dependencies are synchronized and the environment is prepared, restart the development server to load the updated code.

Run all templates simultaneously:

pnpm run dev:all

Or start a specific template in isolation:

pnpm --filter mail dev
pnpm --filter @agent-native/core dev

These commands follow the workflow documented in DEVELOPMENT.md, which provides detailed guidance on workspace-specific development patterns.

Summary

• Pull the latest source from the main branch to receive framework updates and template changes.
• Reinstall dependencies using pnpm install to sync the workspace defined in pnpm-workspace.yaml.
• Execute pnpm run prep from the root package.json to run formatting, type-checking, and security guards.
• Upgrade the CLI independently using npx @agent-native/core@latest to access new commands and features.
• Review packages/core/CHANGELOG.md for breaking changes before migrating existing projects.
• Restart development servers using pnpm run dev:all or filter-specific commands like pnpm --filter mail dev.

Frequently Asked Questions

How do I update the Agent-Native CLI independently?

The CLI is published separately from the monorepo templates. Run npx @agent-native/core@latest followed by your desired command to always fetch the newest published version without globally installing the package. This approach ensures you have access to the latest skill generators and template pickers without modifying your local repository.

What does the pnpm run prep script do?

The prep script, defined in the root package.json, executes a comprehensive preparation suite that includes code formatting, TypeScript type-checking, test execution, and security guard validation. This script mirrors the CI pipeline defined in .github/workflows/ci.yml and ensures your codebase meets the repository's quality standards before you start development or submit changes.

How do I update a specific template instead of the entire workspace?

Agent-Native supports filtering commands to individual workspace packages. Use pnpm --filter <template-name> to target specific templates—for example, pnpm --filter mail install to update dependencies for only the mail template. Refer to the template-specific README files in the templates/ directory for package-specific update instructions.

Where can I find breaking changes for Agent-Native updates?

Breaking changes and migration guides are documented in packages/core/CHANGELOG.md. This file tracks version history for the core framework, including API changes like the outputSchema introduction in v0.54.1. Review this changelog after pulling updates to determine if your existing code requires modifications to remain compatible with the latest framework features.

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