Introduction to plugsuits
Relevant source files
The following files were used as context for generating this wiki page:
plugsuits is a lightweight, barebone AI agent harness built on the Vercel AI SDK. Inspired by the neural interface from Neon Genesis Evangelion, it serves as a minimal, essential connection between a Large Language Model (LLM) and its environment, including code editing, file operations, and shell execution. The project follows a "plug and go" philosophy, aiming to provide a native-feeling interface without abstraction taxes or framework overhead.
Sources: README.md:1-25
The system is structured as a TypeScript monorepo that separates the core agent logic (harness) from specific runtime implementations (TUI, Headless) and specialized agent applications (Code Editing Agent). This modularity allows the core harness to remain model-agnostic and reusable across different agent types.
Sources: AGENTS.md:5-15, packages/harness/README.md:1-10
Architecture Overview
The plugsuits project is organized into four primary packages within a pnpm and Turborepo monorepo. This structure ensures a clean separation of concerns, where the core logic is independent of the user interface or specific task implementations.
Package Hierarchy and Relationships
The following diagram illustrates the dependency flow between the core packages:
This diagram shows that @ai-sdk-tool/harness serves as the foundation for all other packages. Both @ai-sdk-tool/tui (Terminal UI) and @ai-sdk-tool/headless (JSONL streaming) depend on the harness, and the @ai-sdk-tool/cea (Code Editing Agent) integrates all three to provide a full agent implementation.
Sources: AGENTS.md:16-35, packages/tui/AGENTS.md:10-15
Core Components Table
| Package | Name | Description |
|---|---|---|
@ai-sdk-tool/harness | Core Harness | Model-agnostic loop, message history, tool management, and session primitives. |
@ai-sdk-tool/tui | Terminal UI | Primitive components for interactive sessions, including streaming views and spinners. |
@ai-sdk-tool/headless | Headless Runner | JSONL event streaming for CI/CD, benchmarks, and automated workflows. |
@ai-sdk-tool/cea | Code Editing Agent | A specialized implementation focusing on deterministic file editing and shell interaction. |
Sources: README.md:65-75, AGENTS.md:16-35
The Harness Core (@ai-sdk-tool/harness)
The harness provides the foundational primitives required for any AI agent to function. It abstracts the complexities of context management, tool orchestration, and iteration loops.
Key Primitives
- Agent Loop: A model-agnostic iteration mechanism (
runAgentLoop) that handles tool calls, step completions, and stop conditions. - Checkpoint History: Manages conversation history with built-in context compaction to handle token limits effectively.
- Session Management: Provides UUID-based session tracking to isolate different agent interactions.
- Skills Engine: A discovery system that loads "skills" (extended instructions or tool-use patterns) from bundled, global, or project-specific directories.
Sources: packages/harness/README.md:35-150, AGENTS.md:55-75
Agent Execution Flow
The following sequence diagram represents the typical interaction between the harness, the LLM, and the tools:
This flow demonstrates how the harness manages the loop between model reasoning and tool execution, ensuring that history is checkpointed and compacted as needed.
Sources: packages/harness/README.md:14-33, packages/harness/src/compaction-prompts.ts:15-50
Context Management and Compaction
A critical feature of plugsuits is its ability to handle long-running conversations within finite context windows through "compaction."
Compaction Logic
When the token count approaches a model's limit, the harness triggers a summarization process. This process uses the LLM to create a "structured handoff summary" that preserves:
- Current Goal: Verbatim quotes of user requests.
- Files & Changes: Tracks which files were read, modified, or created.
- Technical Discoveries: Architectural decisions and error resolutions.
- Strategy: Alternatives considered and current approach.
- Next Steps: Immediate actions to maintain momentum.
Sources: packages/harness/src/compaction-prompts.ts:15-50, packages/harness/README.md:180-200
Token Thresholds
The system uses a tiered threshold approach for compaction:
- Speculative Ratio: Compaction preparation starts before the limit is reached.
- Blocking Threshold: Prevents new messages if context is dangerously full until compaction is complete.
- Reserve Tokens: Ensures there is always room for the model to generate a summary.
Sources: packages/harness/src/compaction-prompts.ts:250-280, packages/harness/README.md:75-85
Code Editing Agent (CEA) Implementation
The Code Editing Agent is the flagship implementation of the plugsuits harness. It is specifically optimized for software engineering tasks, enforcing strict principles for safety and efficiency.
Core Principles for CEA
- Understand Before Acting: Always read files or explore the structure (via
read_file,grep, orglob) before attempting an edit. - Tool Precision: Uses dedicated tools for file operations rather than shell commands (e.g.,
edit_fileinstead ofsed). - Hashline Edit Engine: Employs deterministic file editing with hash-verified line anchors to prevent stale-state modifications.
- Parallel Execution: Allows calling multiple independent tools in a single response to improve performance.
Sources: packages/cea/src/context/system-prompt.ts:60-120, README.md:25-40
Tool Categories in CEA
| Category | Tools | Purpose |
|---|---|---|
| Modify | edit_file, write_file, delete_file | Deterministic file mutation. |
| Explore | read_file, grep_files, glob_files | Context gathering and searching. |
| Execute | shell_execute, shell_interact | Build, test, and git operations. |
| Planning | load_skill, todo_write | Workflow management and skill loading. |
Sources: packages/cea/src/tools/AGENTS.md:5-25, packages/cea/src/context/system-prompt.ts:5-40
Conclusion
plugsuits provides a robust, modular framework for building AI agents that can interact deeply with codebases and systems. By separating the model-agnostic harness from specialized runtimes and agents, it allows for high technical accuracy, efficient context management, and a low-overhead development experience. Its focus on deterministic tools and clear architectural boundaries makes it suitable for both interactive terminal use and automated headless workflows.
Sources: README.md:5-15, AGENTS.md:5-10