Claude / Codex Agent Harness
Relevant source files
The following files were used as context for generating this wiki page:
The Claude / Codex Agent Harness is a portable contributor interface that enables AI agents to operate the RuView WiFi-sensing system. It provides a secure runtime environment, a reviewed shared brain of repository knowledge, and a Model Context Protocol (MCP) server for tool execution. The harness ensures that AI agents interact with the repository under strict security and accuracy guardrails, particularly regarding WiFi-sensing performance claims.
Sources: harness/ruview/README.md:1-12, CLAUDE.md:1-10, AGENTS.md:37-40
Architecture and Core Components
The harness operates as a set of Node.js tools exposed through a Command Line Interface (CLI) and an MCP server. It utilizes the @metaharness/kernel for cross-platform execution, preferring WebAssembly (WASM) backends. The system distinguishes between the community harness (@ruvnet/ruview) and the focused homecore metaharness.
System Components
| Component | Description |
|---|---|
| CLI / MCP Server | The primary interface for tool execution, supporting both human and agent interactions. |
| Shared Brain | A reviewed, source-cited corpus of repository facts stored in brain/corpus/core.jsonl. |
| Tool Registry | A central repository of functions (ruview_*) that perform diagnostic and operational tasks. |
| Host Adapters | Specific implementations for Claude Code and Codex that enforce read-only defaults and sandboxing. |
| Guardrails | Logic that lints text for untagged accuracy claims and enforces fail-closed operations. |
Sources: harness/ruview/README.md:20-30, harness/homecore/README.md:65-72, harness/ruview/src/tools.js:7-14, CLAUDE.md:58-65
Implementation Diagram
This diagram shows the relationship between the harness, the AI hosts, and the underlying repository structure.
The harness mediates all agent requests to ensure they adhere to repository policy and security rules.
Sources: harness/ruview/src/tools.js:7-14, harness/homecore/README.md:75-80
Security and Trust Model
The harness implements a default-deny policy for mutations. Agents operate in a read-only environment unless explicitly granted write authority by the user.
Execution Rules
- Sandboxing: Host adapters invoke CLIs with safe-mode flags (e.g.,
claude -p --safe-mode). - Input Validation: The harness validates all process, file, and network inputs at the process boundary.
- Fail-Closed Operations: If a dependency or repository check fails, the tool returns an honest negative instead of fabricating success.
- Accuracy Enforcement: The
ruview_claim_checktool lints text to ensure that WiFi-sensing accuracy claims are marked asMEASURED,CLAIMED, orSYNTHETIC.
Sources: CLAUDE.md:80-90, AGENTS.md:15-25, harness/ruview/src/tools.js:7-10, harness/ruview/README.md:10-15
Interaction Flow
The following sequence diagram illustrates the tool execution flow when an agent requests an operation.
Tooling and Functionality
The harness exposes several core tools through the ruview_* namespace. These tools are used for onboarding, diagnostics, and repository exploration.
Core Tool Registry
| Tool Name | Purpose | Implementation File |
|---|---|---|
ruview_onboard | Guides setup paths (Docker, Repo, or Hardware). | harness/ruview/src/tools.js |
ruview_guidance | Provides a source-cited map of capabilities. | harness/ruview/src/guidance.js |
ruview_verify | Runs deterministic Python proofs and reports verdicts. | harness/ruview/src/tools.js |
ruview_claim_check | Scans for untagged accuracy claims. | harness/ruview/src/tools.js |
ruview_memory_search | Searches the reviewed contributor brain. | harness/ruview/src/brain.js |
Sources: harness/ruview/README.md:32-48, harness/ruview/src/tools.js:140-195, harness/ruview/src/guidance.js:15-30
Code Guidance System
The ruview_guidance tool acts as the primary navigation aid for unfamiliar repository work. It categorizes information into topics such as sensing, hardware, homecore, and testing. Every guidance result includes:
- Implementation Maturity: Current status of the feature.
- Source Citations: Direct links to repository files.
- Validation Commands: Specific tests or CLI commands to verify behavior.
- Limitations: Known constraints or data dependencies.
Sources: harness/ruview/src/guidance.js:6-60, harness/ruview/README.md:90-100
Shared Brain and Learning Flywheel
The harness manages repository knowledge through a reviewed corpus and a gated improvement process known as the Flywheel.
Knowledge Management
- Canonical Corpus: Stored in
harness/ruview/brain/corpus/core.jsonl. - Proposals: The
brain proposecommand generates unreviewed JSONL for pull requests but does not mutate the core corpus. - Evidence Tiers: Every record is labeled by evidence type (e.g.,
REPOSITORY,HARDWARE,SYNTHETIC).
Sources: harness/ruview/README.md:130-140, CLAUDE.md:105-115, AGENTS.md:85-95
Flywheel Process
The Flywheel is a self-improvement loop for the harness itself, involving evaluation and promotion of new capabilities.
Usage and Integration
To use the harness, you typically invoke it via npx or register it as an MCP server in your AI host settings.
CLI Examples
# Get guidance on a specific topic
npx @ruvnet/ruview guidance --topic sensing --query "CSI"
# Run the deterministic verification proof
npx @ruvnet/ruview verify
# Check a report for accuracy claim compliance
npx @ruvnet/ruview claim-check --text "WiFi sensing is 100% accurate."
Sources: harness/ruview/README.md:15-25, AGENTS.md:42-50
Integration with Claude Code
The harness includes a .claude/settings.json file to automatically register the MCP server. When running as an agent, the harness enforces "plan mode" and "safe mode" by default to prevent unauthorized mutations.
Sources: harness/ruview/README.md:110-120, CLAUDE.md:85-95, plugins/ruview/README.md:50-55
Summary
The Claude / Codex Agent Harness serves as the authoritative interface for AI interaction within the RuView project. It bridges the gap between raw source code and agent capabilities by providing a secure, tool-enriched environment that enforces repository governance and technical accuracy. Through its guidance system and shared brain, it ensures that all contributor work—whether human or AI—is backed by verifiable evidence and repository policy.
Sources: harness/ruview/README.md:165-170, CLAUDE.md:165-175