Understanding the Monorepo Structure of OpenMAIC: A Complete Guide

OpenMAIC uses a pnpm-based monorepo architecture with apps/, packages/@openmaic/*, configs/, and components/ directories, enabling centralized management of the Next.js frontend, reusable AI agent libraries, and shared configuration files.

The monorepo structure of OpenMAIC organizes all frontend, backend, and shared libraries needed for the AI agent platform into a single cohesive workspace. This pnpm workspace configuration allows the THU-MAIC team to publish scoped packages under @openmaic/* while maintaining atomic versioning and dependency management across the entire ecosystem. Understanding this layout is essential for developers contributing to the agent logic, skill plugins, or web interface.

Top-Level Directory Layout

The repository root follows standard pnpm workspace conventions, separating runnable applications from reusable libraries and configuration files.

• apps/ – Contains standalone runnable applications, primarily the Next.js web interface at apps/web/app/page.tsx
• packages/ – Houses all publishable libraries under the @openmaic/* npm scope
• configs/ – Centralized configuration files including configs/theme.ts for theming and hotkey definitions
• components/ – UI components that are not published as packages but consumed by the web app, such as components/workbench/workspace/WorkspaceShell.tsx
• e2e/ – Playwright end-to-end test suites located in e2e/tests/full-happy-path.spec.ts
• tests/ – Unit and integration tests for various packages, including tests/workbench/workspace-tree.test.ts
• docs/ – Docusaurus-based documentation site, deliberately excluded from the workspace lockfile via pnpm-workspace.yaml
• scripts/ – CI/CD helper scripts and local tooling automation like scripts/build.sh
• public/ – Static assets including public/logo-horizontal.png used by the web UI
• Root configuration files – Global TypeScript (tsconfig.json), ESLint, Prettier, and pnpm-workspace.yaml settings

The packages/ Directory and @openmaic Scope

The packages/ directory contains the core business logic of OpenMAIC, organized as individually versioned npm packages. According to the repository source code, these are structured under packages/@openmaic/* and published to the npm registry under the @openmaic organization scope.

Core AI Agent Logic (@openmaic/agent)

Located at packages/@openmaic/agent, this package contains the fundamental AI agent orchestration logic. It defines the runtime environment for agent execution and exposes the primary Agent class that other applications import to instantiate intelligent workflows.

Plugin Skill Framework (@openmaic/skill)

The packages/@openmaic/skill directory implements the extensible skill system that allows third-party capabilities to be registered dynamically. This framework enables the modular architecture where specific AI capabilities can be added or removed without modifying core agent code.

Shared UI Components (@openmaic/ui)

Found at packages/@openmaic/ui, this library provides theme-aware React components used consistently across the platform. The package exports ThemeProvider and other design system elements that ensure visual consistency between the main web application and any embedded widget contexts.

Configuration and Workspace Wiring

The monorepo structure of OpenMAIC relies on specific configuration files to resolve internal dependencies and manage build pipelines.

pnpm-workspace.yaml defines the workspace boundaries, instructing pnpm to treat all directories under packages/* and packages/@openmaic/* as distinct packages. The configuration explicitly excludes the documentation site using the "!packages/docs" pattern to prevent dependency conflicts between the Docusaurus build and the main application toolchain.

Each package within packages/@openmaic/* maintains its own package.json with defined entry points, enabling independent versioning while allowing the apps/web application to consume them via workspace protocol references.

How Imports Work Across the Workspace

The pnpm workspace configuration automatically resolves internal package imports, allowing the Next.js application to import scoped packages as if they were installed from npm. This enables clean code sharing without relative path traversal.

// Inside apps/web/pages/index.tsx
import { Agent } from '@openmaic/agent'
import { ThemeProvider } from '@openmaic/ui'

export default function Home() {
  return (
    <ThemeProvider theme={theme}>
      <Agent />
    </ThemeProvider>
  )
}

The import paths resolve to their respective src/ directories within packages/@openmaic/agent and packages/@openmaic/ui during development, while production builds use the compiled output defined in each package's package.json main entry field.

Summary

• OpenMAIC organizes code into apps/ for applications and packages/@openmaic/* for publishable libraries, enabling clear separation between the Next.js frontend and reusable AI agent modules.
• pnpm-workspace.yaml controls the monorepo boundaries, explicitly excluding the docs/ directory to isolate documentation build dependencies.
• Scoped packages follow npm publishing standards, with each package in packages/@openmaic/ containing independent package.json files, source directories, and test suites.
• Global configuration lives in configs/ and root-level files, providing shared TypeScript, ESLint, and theme settings consumed by both applications and libraries.
• Relative imports from components/ coexist with workspace imports, allowing non-published UI components to reside outside the packages directory while still being available to the web application.

Frequently Asked Questions

What package manager does OpenMAIC use?

OpenMAIC uses pnpm as its package manager and workspace orchestrator. The repository relies on pnpm-workspace.yaml to define which directories contain workspace packages, enabling efficient hoisting of shared dependencies and atomic installation across the entire monorepo structure.

Where are the publishable libraries located?

All publishable libraries reside in the packages/ directory, specifically under packages/@openmaic/. This includes packages/@openmaic/agent for core AI logic, packages/@openmaic/skill for the plugin framework, and packages/@openmaic/ui for shared React components. Each contains its own package.json and is published to npm under the @openmaic scope.

Why is the docs directory excluded from the workspace?

The docs/ directory is excluded via the "!packages/docs" pattern in pnpm-workspace.yaml because it runs a separate Docusaurus build toolchain that may have conflicting dependency requirements with the main Next.js application. This isolation prevents version conflicts between the documentation site's React dependencies and the primary application runtime.

How does the web application consume shared components?

The web application in apps/web/ consumes shared components through two mechanisms: workspace imports for published packages like @openmaic/ui using standard npm import syntax, and relative path imports for components in the top-level components/ directory that are not published as standalone packages. Both methods resolve automatically through the pnpm workspace configuration and TypeScript path mapping defined in tsconfig.json.

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