Getting Started & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Plugsuits is a model-agnostic AI agent harness designed for code editing, file operations, and shell execution. It is structured as a pnpm monorepo using Turborepo and TypeScript, providing a neural interface between LLMs and local development tools. The project is divided into four primary packages: @ai-sdk-tool/harness (core loop), @ai-sdk-tool/tui (terminal UI), @ai-sdk-tool/headless (JSONL streaming), and @ai-sdk-tool/cea (the reference code-editing agent implementation).
Sources: README.md:1-25, AGENTS.md:5-15
Quick Start & Installation
To run the agent directly using the default Anthropic provider, ensure you have Node.js (>= 22) and pnpm (>= 10) installed.
Execution Methods
| Method | Command | Description |
|---|---|---|
| Direct Run | pnpm dlx plugsuits | Executes the agent without local installation. |
| Interactive Mode | pnpm dev | Launches the TUI for interactive chat and tool use. |
| Headless Mode | pnpm run headless -- "<task>" | Runs the agent in non-interactive mode, emitting JSONL events. |
| Development | pnpm install && pnpm dev | Clones the repo and starts the agent in source mode. |
Sources: README.md:35-55, packages/cea/package.json:35-40
Environment Configuration
Plugsuits strictly enforces environment variable validation using @t3-oss/env-core and Zod. Each package defines its own env.ts schema. Direct access to process.env is considered an anti-pattern.
Required Environment Variables
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY | Required for the default Anthropic model provider. |
ANTHROPIC_BASE_URL | Optional override for API proxying or alternative endpoints. |
ANTHROPIC_MODEL | Optional override for the default model (e.g., claude-3-5-sonnet-20240620). |
Debugging Variables
COMPACTION_DEBUG=1: Enables detailed logging of the context compaction engine on stderr.CONTEXT_LIMIT_OVERRIDE: Manually forces a context window size to test compaction behavior.
Sources: AGENTS.md:60-65, README.md:110-125, packages/minimal-agent/index.ts:25-30
Project Architecture & Dependencies
The project is organized to maintain a one-way dependency flow: harness → tui/headless → cea.
The diagram above illustrates the monorepo package hierarchy and core harness modules.
Tooling & Binary Management
The agent requires specific external binaries to perform advanced searches (e.g., ripgrep). The ToolsManager handles the discovery and automatic installation of these dependencies into a local directory (~/.cea/bin).
Supported Tools
| Tool | Binary | Repo | Purpose |
|---|---|---|---|
| ripgrep | rg | BurntSushi/ripgrep | High-performance content searching across the codebase. |
Initialization Logic
- Check Local Path: Looks for the binary in
~/.cea/bin. - Check System Path: Uses
whichorwhereto find the tool in the global environment. - Auto-Install: If missing and
installable: true, it fetches the latest release from GitHub, extracts the platform-specific archive (tar.gz/zip), and moves the binary to the local bin directory.
Sources: packages/cea/src/utils/tools-manager.ts:18-70, packages/cea/src/utils/tools-manager.ts:115-150
Compaction & Context Management
Plugsuits manages LLM context windows through a specialized compaction system. When the estimated token count approaches the model's limit, the CheckpointHistory triggers a summarization process to condense old messages while preserving critical state.
Configuration Parameters
The CompactionConfig defined in the harness allows fine-tuning of this behavior:
- thresholdRatio: The percentage of the context window (e.g., 0.9) that triggers blocking compaction.
- speculativeStartRatio: Triggers background compaction before the limit is reached.
- keepRecentTokens: The amount of recent conversation to keep verbatim.
- summarizeFn: A callback (usually
createModelSummarizer) that uses an LLM to generate a structured handoff.
The sequence diagram shows the flow of autonomous context compaction during a session.
Sources: packages/harness/src/compaction-prompts.ts:70-100, packages/minimal-agent/index.ts:70-85, packages/harness/src/compaction-prompts.ts:250-270
Summary of Key Commands
Developers working within the monorepo should use the following pnpm scripts:
pnpm install: Set up dependencies and workspace links.pnpm run build: Build all packages in correct dependency order (harnessfirst).pnpm run typecheck: Runstsc --noEmitacross all packages.pnpm test: Executesvitestfor unit and integration tests.pnpm run lint: Fixes code style usingultracite.
Sources: AGENTS.md:120-135, packages/cea/package.json:30-40
Plugsuits provides a robust framework for building autonomous agents by abstracting model providers, managing long-running conversation state through compaction, and providing standardized tool interfaces. Proper configuration of environment variables and the ~/.cea/bin path is essential for full functionality.
Sources: README.md:10-30, AGENTS.md:140-150