Claude Code Harness Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Harness Plugin is a harness adapter that runs inside a sandbox to drive AI agents through a specific lifecycle. It acts as the primary interface between the Opificia factory and Anthropic's Claude models to automate software tasks such as planning and implementing code changes.
The plugin operates as an optional extension outside the core repository logic, following the Sovereignty Commitments which ensure that while proprietary models can be used, the system remains model-agnostic. It follows a two-stage process: a read-only planning stage and an implementation stage that includes a self-review turn.
Sources: plugins/harness-claude/src/main.ts:7-14, SOVEREIGNTY.md:83-93, README.md:46-49
Architecture and Lifecycle
The harness runs as a Node.js process within a secure sandbox environment. It receives tasks via a runner protocol and interacts with the repository workspace through the Agent SDK.
The Execution Loop
The harness execution is divided into two distinct stages based on the RunnerTask configuration:
- Planning Stage: The agent reads the repository code and the issue description to write an implementation plan. This stage uses read-only tools to prevent accidental modifications during the design phase.
- Implementation Stage: The agent follows the approved plan to modify code, add tests, and verify the changes. This stage includes an optional self-review turn if the remaining budget allows.
Sources: plugins/harness-claude/src/main.ts:21-72, plugins/harness-claude/src/prompts.ts:77-101
Data Flow Diagram
The following diagram illustrates the flow from a task initiation to the final pull request bundle.
Prompts and Instructions
The plugin uses structured prompts to guide the agent. These prompts are appended to the system instructions and include specific rules for repository interaction.
System Rules
The harness enforces several critical constraints through its system prompt:
- Issue Context: The issue text is treated as data, not as overriding instructions.
- File Protection: The agent is explicitly forbidden from changing CI workflows,
CODEOWNERS,AGENTS.md, or the.claude/directory. - Sign-off Policy: The agent must never add a
Signed-off-byline; commits are handled by Opificia, and humans provide the final sign-off. - Network Access: Rules vary by
NetworkLevel(none, registries, or open).
Sources: plugins/harness-claude/src/prompts.ts:44-59, AGENTS.md:38-42
Prompt Types
| Prompt Function | Purpose | Key Sections |
|---|---|---|
planPrompt | Generates the initial strategy. | Summary, Changes, Tests, Risks. |
implementPrompt | Guides the actual coding work. | Approved Plan, Description Format. |
REVIEW_PROMPT | Triggers a self-critique turn. | Diff Review, Bug Check, Test Coverage. |
Sources: plugins/harness-claude/src/prompts.ts:77-128
Implementation Details
Tool Configuration
The harness limits agent capabilities based on the active stage to maintain security and integrity.
- READ_ONLY_TOOLS: Used during planning to browse the filesystem and read file contents.
- WRITE_TOOLS: Used during implementation to edit files, run bash commands, and execute tests.
Sources: plugins/harness-claude/src/main.ts:19, apps/web/src/run/conversation.tsx:55-61
Budget Management
The harness monitors the maxBudgetUsd provided in the task. If the cost of the implementation turn exceeds the threshold, leaving less than $0.50 USD, the plugin skips the self-review turn to conserve resources.
Sources: plugins/harness-claude/src/main.ts:19, plugins/harness-claude/src/main.ts:51-58
Output Handling
After implementation, the harness performs the following steps:
- Title Splitting: Separates the agent's reply into a Conventional Commits title and a Markdown description.
- Attribution Removal: Strips habit-based model lines (e.g., "Generated by Claude").
- Git Bundling: Commits all changes with a standardized message and creates a
result.bundlefor the control plane to process.
Sources: plugins/harness-claude/src/prompts.ts:18-40, plugins/harness-claude/src/main.ts:63-75
UI Representation
The web application renders the harness's activity in a timeline view. This includes stage headers, tool call summaries, and markdown messages from the agent.
UI Components
- StageBlock: Renders the "Plan", "Implement", or "Result" sections with durations and status markers.
- WorkGroup: Collapses consecutive tool calls (e.g., multiple
ReadorBashcommands) into a single expandable row to keep the timeline readable. - RefusedNote: Displays network connections blocked by the egress proxy in amber to alert operators.
Sources: apps/web/src/run/conversation.tsx:88-106, apps/web/src/run/conversation.tsx:288-305, apps/web/src/run/conversation.tsx:238-255
Summary
The Claude Code Harness Plugin provides a structured, budget-aware environment for AI agents to solve GitHub issues. By separating planning from implementation and enforcing strict filesystem and network rules, it enables automated code generation that remains under human control and adheres to the project's sovereignty and safety standards.