Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The plugsuits project is structured as a TypeScript monorepo managed with pnpm workspaces and Turborepo. The architecture is designed to decouple the core agent logic from specific implementations, allowing for a model-agnostic harness that can be reused across different user interfaces and execution modes.
The project follows a modular pattern where the core logic resides in @ai-sdk-tool/harness, while specialized packages handle terminal UI rendering, headless event streaming, and the primary code-editing agent implementation.
Sources: AGENTS.md:1-10, README.md:92-100
Package Structure
The monorepo is divided into four primary packages located within the packages/ directory. Each package has a specific role and maintains a strict dependency direction to ensure modularity.
Core Packages
| Package | Name | Role |
|---|---|---|
harness/ | @ai-sdk-tool/harness | Model-agnostic core loop, session management, skills, and tool orchestration. |
tui/ | @ai-sdk-tool/tui | Terminal UI components and stream rendering handlers. |
headless/ | @ai-sdk-tool/headless | JSONL event streaming for CI/CD and automated benchmarks. |
cea/ | @ai-sdk-tool/cea | The Code Editing Agent; integrates the harness, TUI, and headless packages. |
Sources: AGENTS.md:12-25, README.md:102-110
Dependency Flow
The architecture enforces a one-way dependency flow. Packages like harness, tui, and headless are foundational, while cea acts as the consumer of all three. Importing from @ai-sdk-tool/cea into the foundational packages is considered an anti-pattern.
The diagram above illustrates the package dependency hierarchy, showing harness as the base and cea as the top-level implementation.
Sources: AGENTS.md:80-85, packages/cea/package.json:44-47
Build and Task Orchestration
The project uses Turborepo to manage tasks such as building, testing, and linting across the workspace. The root package.json defines canonical scripts that trigger these workspace-wide operations.
Task Management Configuration
Tasks must be executed in a specific order due to package dependencies. The standard build order requires harness to be built first, followed by tui and headless, and finally cea.
{
"scripts": {
"build": "turbo run build",
"dev": "turbo run dev --filter=plugsuits",
"test": "turbo run test",
"typecheck": "pnpm run typecheck:root && turbo run typecheck"
}
}
Sources: package.json:6-12, AGENTS.md:68-71
Development Workflow and Conventions
The monorepo architecture establishes strict conventions for package management, environment variables, and code quality.
Key Infrastructure Rules
- Package Manager: The project uses
pnpm(version 10.x). - TypeScript Resolution: Source files use extensionless imports (e.g.,
import { foo } from "./foo"). A post-build script handles adding.jsextensions for ESM compatibility in thedist/output. - Environment Variables: Raw access to
process.envis an anti-pattern. Instead, the project uses@t3-oss/env-corewith Zod validation in a dedicatedenv.tsfile for each package. - Quality Gates: Linting is split into
check(non-mutating) andlint(auto-fixing), both powered byultracite.
Sources: AGENTS.md:64-75, AGENTS.md:85-93, package.json:15-16
Execution Modes
The architecture supports two distinct entry points for the Code Editing Agent (CEA), managed within packages/cea/src/entrypoints/:
- Interactive (CLI): Utilizes the
@ai-sdk-tool/tuipackage for a full terminal session loop. - Headless: Utilizes the
@ai-sdk-tool/headlesspackage to emit structured JSONL events (user,tool_call,tool_result,assistant,error).
This diagram shows the high-level data flow from the entrypoints through the harness core.
Sources: packages/cea/src/AGENTS.md:20-25, AGENTS.md:46-55
Conclusion
The plugsuits monorepo architecture provides a robust framework for agent development by isolating core logic from peripheral concerns like UI and transport protocols. By leveraging Turborepo and pnpm, the project maintains a clear build pipeline and strict dependency boundaries, ensuring that the @ai-sdk-tool/harness remains a reusable, model-agnostic engine.