Yoetz

Product Introduction

1. Definition: Yoetz is a local-first, open-source work ledger and verification service for AI coding agents. Technically, it is a local daemon that implements the Model Context Protocol (MCP) server and hooks into supported development environments to create an append-only, verifiable audit trail of agent activity.
2. Core Value Proposition: It exists to solve the trust and accountability gap in AI-assisted software development. Yoetz provides deterministic, coverage-bounded verification that an AI agent's claimed work (e.g., "refactored, tests pass") matches the actual, observed actions in the development environment, issuing a formal receipt of what was verified and what remains open.

Main Features

1. Dual-Record Ledger: Yoetz maintains two separate, append-only event streams in a local SQLite database. The first is the agent's claimed work, published via MCP tools (publish_work, check). The second is the host's actual observed events (sessions, tool calls, file edits, test runs), captured via first-party hooks in Codex, Claude Code, and Cursor. This architectural separation is fundamental to its verification model.
2. Deterministic Rule Engine & Receipt Generation: A local rules engine compares the "said" vs. "did" records. Discrepancies are logged as "findings" (e.g., "tests pass cites a run older than the last edit"). The output is a structured receipt that states exactly which obligations were verified, the coverage of the check, and any unresolved findings. This process is deterministic and runs entirely on the user's machine.
3. Local-First & Privacy-Preserving Architecture: All data processing, rule evaluation, and ledger storage occur locally. No source code, file contents, or agent conversation history is transmitted externally. An optional "reviewer model" feature uses the user's own API key or ChatGPT plan, ensuring no data passes through Yoetz's servers.
4. First-Party IDE/Agent Integration: Unlike generic monitoring tools, Yoetz provides deep, official integrations. It acts as an MCP server for any compatible agent and installs direct hooks into specific hosts (Codex, Claude Code, Cursor) to capture granular, structured development events without manual instrumentation.

Problems Solved

1. Pain Point: The "black box" nature of AI coding agents, where users cannot automatically verify if an agent's summary of completed work is accurate, complete, and based on current evidence. This leads to manual oversight, missed regressions, and broken trust in automation.
2. Target Audience: Software engineers and developers who regularly use AI coding agents (like Cursor, Codex, Claude Code) for substantive tasks such as refactoring, feature implementation, and test writing. It is particularly valuable for senior developers and tech leads managing agent output in critical or complex codebases.
3. Use Cases: Essential for verifying a refactoring job where the agent must preserve API shape; validating that a "tests pass" claim is based on a test run executed after the final code change; providing an audit trail for regulatory or compliance-sensitive development; and coordinating work between multiple AI agents on the same project to prevent conflicts.

Unique Advantages

1. Differentiation: Unlike simple activity loggers or CI/CD systems, Yoetz does not just record events—it actively verifies claims against evidence. Compared to traditional testing, it provides a real-time, claim-specific verification layer that is integrated directly into the agent's workflow, not a separate pipeline.
2. Key Innovation: The "coverage-bounded receipt." Yoetz does not guarantee the code is perfect; it guarantees the verification is precisely scoped. The receipt explicitly states what was checked (e.g., "verified 2 of 3 obligations") and what was out of scope, providing a clear, honest boundary of accountability for both the human and the AI agent.

Frequently Asked Questions (FAQ)

1. How does Yoetz verify AI agent work without sending my code to the cloud? Yoetz operates on a strict local-first principle. It runs as a single service on your machine. The verification rules compare the agent's MCP-published claims against the event stream captured by local IDE hooks, all processed within your local environment using SQLite. No source code leaves your computer.
2. What AI coding agents and IDEs are compatible with Yoetz? Yoetz offers first-party, official support for Codex, Claude Code, and Cursor through dedicated hooks. Furthermore, any AI agent or development environment that can act as an MCP client can publish claims to Yoetz, making it extensible to other tools in the ecosystem.
3. Can Yoetz run tests or guarantee my code is bug-free? No. Yoetz is a verification ledger, not a testing framework. It verifies that claimed actions (like "ran pytest") have corresponding observed evidence (a pytest run with results). It checks for consistency and coverage between claim and evidence but does not execute tests or analyze code quality itself.
4. Is Yoetz an open-source project, and what is its license? Yes, Yoetz is fully open-source. Its source code is available on GitHub under the permissive Apache License 2.0, allowing for inspection, contribution, and commercial use.
5. What does "coverage-bounded" mean in the context of a Yoetz receipt? It means the receipt explicitly defines the limits of its verification. It will state which specific obligations from the agent's plan were checked and which findings were identified. It does not imply the entire code change is correct, only that the stated verification steps were performed against the available evidence.